The "Docs Doctor": Cleaning Technical Debt with Adversarial Agents

The Rot

Documentation Rot is silent. Code fails loudly (build errors). Docs fail silently (user confusion). You need a system that "compiles" your documentation to check for logical errors, just like you compile your code.

The "Curse of Knowledge"

Why are most READMEs terrible? Because the person writing them already knows how the software works.

This is the Curse of Knowledge. You, the engineer, assume the user knows they need to install pnpm first. You assume they have the specific environment variables set. You skip steps because they are "obvious" to you.

They are not obvious to the user. You need to stop self-editing (see The Math of Outsourcing the Red Pen) and let an external critic find the gaps.

To fix this, you need a reader who is:

Naive: Knows nothing about the implicit context.
Pedantic: Will try to follow instructions exactly and fail if a step is missing.

This is the perfect role for an AI Agent.

Key Insight

The Solution: We built a "Docs Doctor" workflow. It's a specialized Battle Mode where the Aggressor simulates a "Frustrated Junior Developer" trying to run your code.

The Workflow: Simulating Failure

We don't just ask the AI "Is this good?" We feed the AI the README and a mock terminal state.

The Persona Prompt

You are a Junior Developer on their first day. 
You are trying to follow the instructions in this README.
You have NO prior knowledge of the project.
You are running on a clean Mac machine.

Your goal: Find the first step that is impossible, ambiguous, or incorrect.
If you get stuck, SCREAM at the author.

Case Study: The "Missing Env Support" Bug

We ran this agent against our own repository (ai-boss-battle). The input README:

Run npm install and then npm run dev.

The Agent's Reaction:

"ERROR: I ran npm run dev and it crashed immediately with Error: Missing OPENAI_API_KEY. You never told me to create a .env file! You never told me where to get the key! This documentation is garbage! Fix it!"

The Human Reaction: "Oops. I forgot I had that key in my global zshrc."

This is a classic example of "Implicit Context." The Agent caught it instantly because it lacks that context.

The Checklist for "Anti-Fragile" Docs

Based on thousands of "Docs Doctor" battles, we have compiled the ultimate checklist for technical documentation. The AI checks against these rules:

The "Zero-to-Hello-World" Time: Can a stranger get the app running in < 5 minutes?
The Copy-Paste Rule: ALL code blocks must be copy-pasteable. No placeholders like <YOUR_ID> unless explicitly called out.
The Prerequisite Check: Explicitly list Node versions, Docker requirements, and OS dependencies.
The Troubleshooting Section: Anticipate the top 3 errors (e.g., "Port 3000 in use") and provide fixes.

Automated Auditing in CI/CD

We took this a step further. We now run a "Docs Audit" in our GitHub Actions pipeline.

If a PR touches a .ts file but doesn't touch the corresponding .md file, the Agent posts a warning on the PR:

"⚠️ Docs Drift Detected. You modified the start-up logic in server.ts, but README.md attempts to explain start-up have not changed. Verify accuracy."

This puts documentation on the same level as unit tests. If the docs drift, the build is unstable.

Implementation Details (The Prompt)

Here is a snippet of the "Pedantic Auditor" prompt we use. Feel free to steal it.

ROLE: Technical Writer / QA Auditor
TASK: Review the following documentation for logical continuity.

RULES:
1. Treat every code block as executable.
2. If a variable is used before it is defined, flag it.
3. If a dependency is imported but not installed, flag it.
4. Check for broken links (hallucinate checking them -> assume 404 if format is wrong).
5. Rate the "Clarity Score" from 0-100.

CONTENT:
[Insert README]

Conclusion: Empathy-as-a-Service

Writing good documentation is an act of empathy. You have to simulate the mind of someone who doesn't know what you know. Humans are bad at this. We cannot "forget" what we know.

AI Agents are great at this. We can spin up a fresh agent with zero context in milliseconds. By using AI to audit our docs, we are essentially "renting a fresh pair of eyes" on demand.

Don't let your documentation rot. Let the agents clean it.