The end of documentation debt: how an AI “memory prosthesis” automates the PRD

Product documentation has a dirty secret: it decays on contact with reality.

The moment a PRD is “final,” implementation starts moving—edge cases appear, state rules evolve, performance constraints bite, and someone makes a pragmatic tradeoff that never makes it back into the doc. Within days, you’re left with a document that sounds right, but isn’t true.

That gap is documentation debt, and it’s a debt that compounds.

The problem: PRDs become a dead language

In traditional product development, a PRD is written in human intent while the product is built in system behavior. Over time, those two languages diverge.

The result is what I call a Cognitive Mirage:

• Everyone feels aligned because there’s a document and a Figma file.
• But developers (and AI agents) are operating with partial or outdated truth.
• You get coherence drift—the slow, invisible misalignment between “what we think we built” and “what the system actually does.”

AI doesn’t automatically solve this. In fact, it often makes it worse. If your workflow is: “here’s a screenshot, here’s some prompting, now write me a PRD” - you’re not automating documentation, you’re just writing documentation in prompt form. That defeats the purpose.

The solution: stop prompting; start extracting

A reliable AI-driven documentation flow isn’t a clever prompt. It’s an operating model.

The shift is simple:

• Figma is UI truth (visual intent, layout, interaction affordances).
• Code is behavioral truth (states, rules, constraints, edge cases, contracts).

Then you build a system that lets AI generate docs as a technical extraction from those truths—not interpretive creative writing.

To do that, you need two things:

1. a persistent navigation layer (so the AI doesn’t get lost and burn context),
2. a zero-trust evidence policy (so it can’t hallucinate its way into confidence).

1) The strategy: architecture as a persistence layer

LLMs don’t “remember” your project. They regenerate answers from the context you give them. So if you want stable outputs across a large codebase, you must externalize project memory into a lightweight system the AI can consult repeatedly.

Think of it as giving the AI:

• a map of where truth lives,
• and a rule that it must check the map before it speaks.

This is the core reason “context window fatigue” happens in large repos: the model has no navigation constraints, so it wastes tokens roaming.

A navigation layer fixes that. It turns your repo from “a blob” into something addressable.

If you’re interested in leanring more about context fatigue and how I propose solving it, please read my article on The AI Memory Prosthesis.

UI truth vs behavioral truth (and why it matters)

This distinction is the key to reducing translation tax:

• Figma captures what users should see.
• Code captures what the product can actually do.

If your PRD describes behavior that only exists implicitly in visuals, someone has to translate it. That “someone” becomes you, or your prompts. However, when behavior is encoded in the codebase (states, rules, edge cases), the AI can extract it.

2) The protocol: “Zero-Trust” documentation

The biggest risk in AI-generated docs is not that the AI is “bad” at documenting, it’s that it’s confident. So the real solution isn’t necessarily “better prompting,” as much as it’s installing guardrails.

The Evidence Rule (anti-hallucination)

For every claim about behavior or logic, the AI must:

• Cite evidence: file path + function/component name (or a specific Figma frame if relevant).
• Admit uncertainty: if evidence is missing, it must output UNKNOWN / NEEDS DECISION.

That turns documentation into something better than a narrative:

• a gap analysis tool for missing logic,
• and an audit trail for what’s real vs assumed.

Templates > prompts

Templates are how you control quality.

Without a template, the AI will do what it always does:

• over-explain,
• invent “nice-to-haves,”
• and drift into generic product writing.

A PRD template forces structure and intent:

• what counts as requirements,
• what counts as assumptions,
• what counts as “we need a decision.”

3) The operating model: a deterministic environment

If you want consistent AI docs, you need consistent inputs and consistent rules.

Here’s the minimal structure that makes it work:

A. Rules of Engagement (AGENTS.md)

A single root-level file the AI must read first:

• navigation guidance (where to look first)
• source-of-truth priority (code vs figma)
• output rules (citations, UNKNOWN protocol, templates)

B. Templates (/docs/templates/) — read-only

Canonical templates the AI fills (but never edits):

• PRD_TEMPLATE.md
• SPEC_DELTA_TEMPLATE.md
• QA_PLAN.md

C. Outputs (/docs/prd/)

Generated docs saved as:

• YYYY-MM-DD_feature-name.md This makes docs versioned, reviewable, and searchable.

4) When to generate: milestones > continuous

AI loves to document. If you let it, it will happily generate 30 pages of “context” and burn through your usage limits. So don’t do continuous auto-documentation by default unless you have strong, meticulous, and very strict guardrails and operational rules set in place.

Instead, I recommend triggering documentation only when it’s high leverage:

• feature handoff (design → engineering)
• user-facing behavior changes (states, rules, edge cases)
• data contracts change (API/storage/events)
• major decisions are made

The “Documentation Threshold” rule

A better future state isn’t auto-writing docs constantly, but rather it’s having the AI proposing the update moment, and humans approving it.

In practice:

• The agent monitors for doc-worthy changes after running a series of code changes (based on file paths / diff patterns).
• It posts: “Documentation update recommended: why + which template + which doc.”
• You approve, then it writes.

That keeps costs sane and avoids documentation noise - Trust me, nothing is as painful as sitting there watching Claude spend 5 mins auto-generating a documentation you didn’t want to update, and burning through your usage limits.

5) The next evolution: Builder + Historian

Once the MVP is stable, you can fully offload documentation via specialization:

• Agent A (Builder): codes the feature + tests and produces a short “what changed/why” summary.
• Agent B (Historian): scans diffs + critical paths and updates docs using templates + evidence rules.

Pros

• Docs stay in sync with the codebase
• Less context switching for builders
• Consistent outputs
• Reviewable in PR diffs (auditable)

Cons

• Needs setup + strict guardrails
• Can get noisy/costly without thresholds
• Risk of “confident wrongness” without mandatory citations + UNKNOWN protocol

The pattern is simple:

One agent ships. One agent keeps the system coherent.

The key insight: AI-native documentation isn’t about writing, as much as it’s about extraction.

Most teams treat documentation as a writing task, which is exactly why it rots fast.

In an AI-native workflow, documentation becomes:

• a structured extraction from sources of truth,
• governed by evidence,
• triggered only when it matters.

Manual documentation dies the moment you stop asking humans to re-explain what the system already knows.

If you want to go deeper

This post focuses on standardizing an AI-driven documentation workflow: rules, templates, evidence, and triggers.

If you want the deeper mechanics of context continuity and self-orienting workflows, I’ve written a full paper on the broader “AI Memory Prosthesis” idea and how to prevent coherence drift across long-running projects.