Reading Osmani’s agent harness post triggered an audit instead of a copy. The first pass came back saying three of my repo clones had let their instruction file drift from the master and that I needed a sync mechanism. I told it to go ahead, and it wrote a script that could copy the master file over the others. Then the re-check showed two of those three matched the master exactly and only one had drifted. I said I wasn’t clear on this and wanted the best long-term solution, and the answer was not to build sync tooling at all, just to use git. I had the script deleted. In the end I deleted stale the cockpit/docs, rejected clone-sync tooling for git plus ai/sync, and wired drift detection into /sync-vault. The fix was fewer copies of the truth, not more machinery to reconcile them.
The right fix for doc drift was less tooling, not more
AI Skills
Use this lesson with the AI assistant you already use
A first-pass audit claimed three repo clones had drifted instruction files. A re-check after building a sync script found only one actually had, and the best long-term fix turned out to be deleting the script and using git instead.
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: Verify the drift claim before building tooling to fix it
SOURCE: dxdev.com/blog/2026-05-10_doc-drift-less-tooling
WHAT HAPPENED: A first-pass audit claimed three repository clones had let their instruction file drift from the master copy and needed a sync mechanism, and a script was written to copy the master file over the others. A re-check afterward showed two of those three actually matched the master exactly, and only one had genuinely drifted. Asking for the best long-term solution rather than a quick patch led to deleting the sync script entirely, using git itself instead of custom sync tooling, and wiring drift detection into an existing command.
THE RULE: Before building tooling to fix a diagnosed problem, such as config drift across clones, verify the diagnosis's actual scope, and prefer using existing mechanisms, such as git, over building new bespoke tooling to solve a problem that already has a standard solution.
CHECK MY CODE, then report PASS or FAIL with file:line for each:
1. Any automated audit's finding, such as "N files have drifted," acted on by building new tooling before re-verifying the actual scope of the finding.
2. Any new sync or reconciliation script built to solve a config-drift problem that an existing mechanism, such as git or an existing command, could already solve.
3. Any decision to build custom tooling made without first asking whether reducing the number of copies of the truth would resolve the problem instead.
THEN PRINT: a table (check, PASS/FAIL, evidence, fix) + a verdict (applies / partially / OUT_OF_SCOPE / no) + the single most important next action.
Prefer to talk it through first? See the AI workflow assessment or get in touch.
Lesson: Verify the drift claim before building tooling to fix it
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.