Software Engineering's Last Black Box

TL;DR. Version control solved "who changed what and when." The industry has no equivalent for "why is this code here, what business rule does it serve, and where did that rule come from?" Fabriq's evidence-first philosophy closes this gap: every cognitive artifact carries sources[] that link back to the specific code that inspired it, validated by a deterministic engine before anything touches the workspace.

The black box#

Walk up to any non-trivial codebase and pick a file at random. Open it. Find a non-trivial function.

Now answer: why does this function exist?

Not "what does it do" — the code tells you that. But why: what product requirement motivated it, which business rule does it implement, what trade-off was made when it was written this way vs. another way?

Most of the time, you can't answer. The information existed once — in a PR description, a Slack thread, a Notion doc, someone's head — but it rotted. The code remained, and the context evaporated.

This is software engineering's last black box. We solved the "who changed what" problem with version control. We solved the "what is this code doing" problem with readable code and tests. We never solved the "why does this code exist" problem — and AI-generated code makes it exponentially worse.

How we got here#

1980s–2000s: Version control. RCS, CVS, Subversion, Git. We learned to track every change, tag releases, branch and merge. The atomic unit was the diff. The question answered was "who changed what, and when."

2000s–2020s: Code review. GitHub pull requests, Gerrit, Phabricator. We learned to review changes before they land. The atomic unit was the PR. The question was "does this change look correct?"

2020s–present: AI generation. Copilot, Cursor, Claude Code. We learned to generate entire features from natural language descriptions. The atomic unit is the conversation. The question is... still "does this change look correct?" — but now the change is 10x larger and the reviewer has 10x less context.

The pattern is clear: each era increased the rate of code production while the capture of intent stayed flat or declined. AI didn't create the "why" problem — it just made it impossible to ignore.

Why "why" matters#

Skipping the "why" has concrete costs:

Onboarding. A new engineer spends their first weeks mapping code to business context. If the "why" was never captured, they have to reconstruct it from git log archaeology and asking people — who may have forgotten or left.

Refactoring. You want to simplify a module. Which behaviors are essential and which are accidental? Without knowing why each piece exists, you either preserve everything (no simplification) or break something (dangerous simplification).

Bug investigation. A payment validation fails. Was the validation rule derived from a compliance requirement or a product decision? If it was compliance and you "fix" it by removing the check, you've introduced a regulatory violation.

AI handoff. You're starting a new feature and you want the AI agent to understand the existing codebase context. If the knowledge about why things were built a certain way exists only in human heads, the AI starts every session from zero.

The evidence-first approach#

Fabriq's answer is an architectural pattern we call evidence-first development. The core idea is simple:

Every knowledge artifact produced during development must carry verifiable links back to the source code that inspired it.

Concretely, this means:

1. Cognitive artifacts with provenance#

When the AI scanner extracts a business rule from the codebase, it produces a structured YAML artifact:

kind: business-rule
name: "Refund window is 30 days from purchase"
sources:
  - file: src/services/RefundService.java
    symbol_handle: RefundService#validateRefundWindow
    kind: fact
  - file: docs/specs/refund-policy.md
    symbol_handle: ""
    kind: inference

Every claim has a sources[] array. Each source specifies:

• The exact file and symbol (not a line number — a symbol handle that survives refactoring)
• The evidence kind: fact (engine-verified), inference (AI-reasoned but plausible), or unknown (needs human review)

2. Engine validation before commit#

The LLM proposes artifacts; the engine revalidates them. Before any artifact enters the workspace, the engine:

1. Resolves every symbol_handle via Tree-sitter to confirm the symbol still exists
2. Checks that fact-level claims actually resolve to real code locations
3. Demotes unverifiable claims from fact to inference automatically
4. Rejects artifacts with unresolvable critical dependencies

This prevents the single biggest failure mode of AI-generated documentation: hallucinated evidence. An LLM can write a convincing claim about a function that doesn't exist. The engine catches it before it pollutes the workspace.

3. Three-level evidence scale#

We use three confidence levels, each with a different policy:

The scale is designed so that unknown is never a terminal state. There's always a path to resolve it — either the AI re-examines the code and finds evidence, or a human provides the missing context.

What this changes#

Evidence-first development changes the economics of knowledge in software engineering:

Before evidence-first. Knowledge flows: human → code → (PR description | Slack | forgotten). Over time, all that remains is code.

After evidence-first. Knowledge flows: human + AI → code + structured artifacts. The artifacts are validated, versioned, and linked to the code that inspired them. Six months later, you can still answer "why is this code here" by reading the artifacts that were produced alongside it.

The artifacts become the answer to "what did the AI actually understand about my codebase?" If someone asks "does the AI know our refund policy?", you don't guess — you read the business rule artifact in the workspace.

Practical impact#

We've been using this approach in Fabriq's own development. The practical effects we've observed:

• Knowledge survives refactoring. When we renamed a major module, the evidence chain adapted automatically because symbols resolved correctly through the rename.
• Onboarding is faster. New contributors read cognitive artifacts alongside code. They understand why before they need to understand what.
• AI handoff is consistent. When starting a new feature, the agent reads the workspace's cognitive index. It doesn't start from zero — it knows what the team has already learned.
• PR reviews are shorter. Reviewers can focus on "does this implementation match the intent?" because the intent is documented alongside the code.

The bigger picture#

Evidence-first development is not a feature — it's a discipline. It requires admitting that code alone is insufficient documentation of intent. It requires building tools that make provenance capture automatic rather than optional. And it requires trusting a deterministic engine over a probabilistic LLM when they disagree.

But the alternative — continuing to build software where the "why" evaporates the moment a PR is merged — is increasingly expensive in an AI-first world. If we can't answer why our code exists, we can't delegate confidently. And if we can't delegate confidently, AI coding agents remain a productivity hack rather than a trusted collaboration partner.

Software engineering's last black box is the one inside our own process. We built Fabriq to open it.

Evidence-first is built into Fabriq's core. Download Fabriq and see it in action, or read the CDR technical spec for the full architecture.