The Repo Had Two Documentation Trees and One Was Labeled "Not for AI

Jul 23, 2026 · 4 min read

The audit counted 621 reference files in docs/ and 57 files in dev-notes/, whose top level label said NOT for AI.

That was the moment the repository stopped looking merely untidy. Our agents were being given two nearby documentation trees with contradictory instructions. docs/ was deliberately organized, portal indexed, and full of architecture, database, goals, strategy, and setup material. dev-notes/ was a catchall with a warning label. An agent would not announce that it had followed the obvious tree and skipped the other one. It would read a plausible answer from docs/, complete the task, and leave us no trace of the fact that it chose the wrong source.

I ran a 13 agent review of the top level to find out what the directory names were actually telling people and agents to do. The review used one investigator per directory, three competing structure proposals, a judge, and two adversarial verifiers. The verifiers grepped both the repository and the shared command workspace for every path the migration would touch. They did not return clean. They returned safe with fixes, which is exactly the result I wanted before moving anything.

The tree that said not to read it

dev-notes/ was not one thing. It was three incompatible things wearing one name.

First, 6_Migration/ held the per ticket DDL archive. It was already cross linked from docs/db/README.md, so it was not only relevant to agents. It was already part of their database trail. Second, 0_Release/ held human GUI click runbooks that were still being edited on July 13. Third, 2_Design/, 3_Setup/, and 9_Dev-Tools/ were stale stubs, except that one verifier found real design and implementation material hiding among them.

The NOT for AI label was therefore worse than a bad name. It was a false routing rule. The migration history belonged in the reference tree because agents were pointed at it. The GUI runbooks needed a human only home. The stubs needed to be salvaged or removed. Leaving all three behind one sign forced every reader to infer exceptions from folder archaeology.

We considered folding everything into docs/internal/. It lost because the directory name would still describe content rather than audience. An agent does not reliably treat internal as a boundary, especially after it has been given a repository wide task. The better test was mechanical: is an agent ever pointed at this artifact? If yes, it belongs in docs/. If no, it belongs in human-notes/.

That meant moving the DDL archive before renaming the old tree:

git mv dev-notes/6_Migration docs/db/migrations
git mv dev-notes human-notes

The order matters. The first move preserves the agent facing path as an explicit database decision. The second makes the remaining tree tell the truth about its audience.

Three places to put a script is not a convention

The same audit found three answers to the question, “where does a script go?”

There was an unmanaged scripts/ directory with three files and no README. There was tools/, already documented as the home for standalone development and maintenance tooling. There was also ai/scripts/, which looked duplicative until we checked its callers. Shared agent commands depended on ai/shared/*, and the Git hooks path pointed at ai/scripts/git-hooks.

A shallow cleanup would have folded every script into tools/. That would have been wrong. ai/scripts/ is agent command glue, not general development tooling. It is a frozen interface. tools/ is the one home for scripts that operate on the repository or development environment. The orphaned scripts/ directory duplicated that charter and had no reason to survive.

The final moves were deliberately boring:

git mv scripts/fetch_issuetype_icons.py tools/jira/
git mv scripts/iis-tracing-custom-fields.ps1 tools/local-dev/
git mv scripts/docs/check-doc-refs.py tools/docs/
git rm -r scripts

Boring is useful here. A newcomer can now predict where a database schema helper, a local development script, or a documentation check belongs. An agent gets fewer plausible but wrong paths to search.

Seven content directories, not ten guesses

The repository had grown to 10 content directories around an 8,187 file application and a 66 file agent layer. We explicitly left the application internals alone. We also left the agent layer and the root environment anchor alone because the shared commands depended on both.

The target has seven self evident content directories: app/, ai/, docs/, human-notes/, tools/, infra/, and archive/. The empty library/ husk goes away because it collides with a live directory inside the application. temp/ goes away because a gitignored .tmp/ already replaced it. zArchive/ becomes archive/, which says what it is without a capitalization or sort trick.

The remaining ambiguous choice was the service configuration package. A sibling repository uses winsw/, which offered cross repository consistency. We preferred infra/otel-collector/ for newcomer guessability and room for future non product services, but left that decision visible rather than pretending there was no tradeoff.

The result is not a preference for fewer folders at any price. It is one canonical home per axis. The exception is intentional: ai/scripts/ stays because its axis is agent execution, while tools/ owns development tooling.

A rename is still a migration

The review got useful when it stopped discussing folder names and started checking couplings.

A live product JavaScript file had a case 'dev-notes': branch for the documentation portal. The reference checker did not scan .sql, so migration files could retain stale internal paths after the Markdown pass went green. The portal appeared to list only .md and .txt files, but moving raw DDL under docs/db/migrations/ still required verification before merge. The repository side rename also did not prove that a live Windows service would find its next install or update from the new configuration path.

The largest operational risk was ten working clones. Git tracked renames can converge through the feature branch and the normal sync path. Empty untracked directories do not. A clone that updates code but retains its old local husks becomes its own ambiguous repository.

So this is a single locked feature branch, not a background cleanup. The completion gate is both the moved checker and a repository wide reference sweep. Its allowlist becomes the machine readable version of the top level contract:

PATH_RE = r"^(app|ai|docs|human-notes|tools|infra|archive)/"

Then the gate must be green:

python tools/docs/check-doc-refs.py

The real problem was never that we had 10 directories. It was that a directory name could silently make the wrong source look authoritative. Agents do not tell you which branch of a messy repository they did not read. They just produce an answer that looks finished.

A repository is part of an agent’s interface. Names, paths, allowlists, and cross links are routing instructions. If those instructions disagree, the failure hides in a result that sounds confident. The fix is not deleting detail. It is giving every useful artifact one truthful, predictable home.

AI Skills

Use this lesson with the AI assistant you already use

A repository had two documentation trees, a curated reference tree and a catchall labeled not for AI that actually held agent-relevant migration history, human-only runbooks, and hidden design material, and an agent given a broad task never announces which tree it actually read.

Paste the prompt, share only the context needed to answer it, and treat the result as a draft for your review. Do not include confidential information or let an AI assistant make changes without your approval.

Optional: for a visual report and saved memory, run /dxdev first. Don’t have it? Get it at dxdev.com/skills/dxdev. The prompt works without it.

dxdev LESSON · paste into your AI coding agent
LESSON: A directory labeled by content rather than intended audience is a routing instruction that fails silently the moment a broad task reaches it anyway
SOURCE: dxdev.com/blog/2026-08-22_two-doc-trees-one-repo
WHAT HAPPENED: A repository had two documentation trees existing side by side: a curated, deliberately organized reference tree, and a much smaller catchall labeled as off-limits to AI, which actually contained three incompatible things, migration history already cross-linked from the main documentation and therefore relevant to agents, human-only setup runbooks, and stale stubs hiding real design material. Because an agent given a repository-wide task never announces which of two trees it actually consulted, a wrong answer read from the more obvious tree looked exactly as confident as a right one. A structured review, competing proposals judged and adversarially checked against every path a change would touch, established a mechanical replacement for the content-based label: whether an agent is ever pointed at a given artifact, not a vague internal designation an agent given a broad task cannot reliably respect. The migration itself was treated as a real migration rather than a casual rename, run on a single locked branch gated by a repository-wide reference sweep, because of real couplings a simple rename would have silently broken: a live product file with a hardcoded path string, a reference checker that did not scan every file type and could go green while leaving stale paths behind, and ten separate working clones where tracked renames converge automatically but leftover empty directories do not, risking each clone becoming its own quietly inconsistent copy of the repository.
THE RULE: A directory or file naming scheme is part of an agent's interface, not decoration; a name describing content rather than intended audience or authority level is a routing instruction a broad-task agent can silently misread, and the failure stays invisible because the agent never announces which source it chose or skipped, it simply produces a confident-sounding answer either way.
CHECK MY CODE, then report PASS or FAIL with file:line for each:
      1. Any directory, file, or documentation tree named for its content or history rather than its intended audience or authority level, especially one carrying an exception or warning label that depends on a reader noticing and obeying it.
      2. Any repository restructuring or rename treated as a simple move rather than a migration with a completion gate, when multiple working copies, clones, deployed configs, or hardcoded path references exist that will not automatically converge.
      3. Any automated reference or link checker whose scope, such as which file types or path patterns it scans, has not been verified to cover every place a moved path could be referenced.
THEN PRINT: a table (check, PASS/FAIL, evidence, fix) + a verdict (applies / partially / OUT_OF_SCOPE / no) + the single most important next action.

Send us what your agent found →

Prefer to talk it through first? See the AI workflow assessment or get in touch.

Lesson: A directory labeled by content rather than intended audience is a routing instruction that fails silently the moment a broad task reaches it anyway

Choose your next level of detail

Want the practical version?

How AI Helps starts with the work problem, what improves, and where human judgment still matters.

See how AI helps Start a conversation