Repair Docs Drift with AI Engineers in Daytona

authors/rohit_m.md

@@ -0,0 +1,5 @@
+Author: Rohit M. Title: Independent Contributor Description: Rohit M. is an
+independent contributor focused on practical developer workflows, documentation
+quality, and AI-assisted engineering systems. He likes turning rough technical
+processes into clear guides that help teams reproduce work safely and ship with
+less confusion.

definitions/20260619_definition_docs_drift_repair.md

@@ -0,0 +1,23 @@
+---
+title: 'Docs Drift Repair'
+description: 'A workflow for finding and fixing documentation that no longer matches the code.'
+date: 2026-06-19
+author: 'Rohit M.'
+---
+
+# Docs Drift Repair
+
+## Definition
+
+Docs drift repair is the process of finding places where a README, setup guide,
+runbook, or release note no longer matches the current code, then correcting the
+smallest useful piece of documentation so the next user can reproduce the
+workflow without guessing.
+
+## Context and Usage
+
+Docs drift usually appears after a command is renamed, a package entry point is
+moved, an environment variable changes, or a setup step is simplified but the
+README is not updated. In an AI engineering workflow, one assistant can map the
+drift across the repository while another reviews the proposed patch and checks
+whether the corrected instructions are safe to publish.

guides/20260619_repair_docs_drift_with_omni_and_claude_engineer_in_daytona.md

@@ -0,0 +1,273 @@
+---
+title: 'Repair Docs Drift with AI Engineers in Daytona'
+description: 'Run Omni Engineer and Claude Engineer in Daytona to find, patch, and review documentation drift safely.'
+date: 2026-06-19
+author: 'Rohit M.'
+tags: ['daytona', 'dev-containers', 'ai-engineering', 'documentation']
+---
+
+# Repair Docs Drift with AI Engineers in Daytona
+
+Documentation usually starts as a promise. A README says which command to run, a
+setup guide names the required environment variables, and a release note tells a
+teammate what changed. Then the code moves. A script becomes a module, a package
+entry point changes, or a team switches from `pip` to `uv`. The docs still look
+polished, but the next developer loses an hour trying commands that no longer
+match the repository.
+
+This guide shows a practical way to repair that kind of drift in a Daytona
+workspace with two AI engineering tools. Omni Engineer does the first pass: it
+maps the repository, compares the README against the code, and proposes the
+smallest documentation patch. Claude Engineer does the second pass: it reviews
+the patch, checks the release-readiness notes, and looks for any instruction
+that could confuse a future maintainer.
+
+The result is not a giant AI rewrite. It is a focused docs-drift repair workflow
+that produces a small patch, clear review notes, and a reproducible workspace.
+That is exactly the kind of work Daytona is good at: every command, dependency,
+and environment variable lives in an isolated development environment instead of
+being hidden on one person's laptop.
+
+![Docs drift repair workflow](/assets/20260619_repair_docs_drift_with_omni_and_claude_engineer_in_daytona_workflow.svg)
+
+## TL;DR
+
+- Use Daytona to open clean, reproducible workspaces for Omni Engineer and
+  Claude Engineer.
+- Keep API keys in workspace environment variables, not in Git.
+- Ask Omni Engineer to map documentation claims against the actual repository
+  entry points.
+- Ask Claude Engineer to review the patch and release-readiness checklist.
+- Ship the smallest documentation change that makes the next run reproducible.
+
+## What you will build
+
+You will use a tiny demo repository with an intentional README mismatch. The
+README asks the reader to run an old command, while the package exposes a newer
+entry point. That is the drift. Omni Engineer will find the mismatch and suggest
+the patch. Claude Engineer will review the corrected command and the release
+notes before you open a pull request.
+
+The same workflow works for larger repositories. A service README might point to
+an old Docker Compose file. A CLI guide might name a removed flag. A project
+setup page might forget a new environment variable. The pattern is the same:
+compare what the docs promise with what the code actually supports.
+
+## Prerequisites
+
+You need:
+
+- A Daytona account and access to create workspaces.
+- A GitHub account for the repositories you want to inspect.
+- `OPENROUTER_API_KEY` for Omni Engineer.
+- `ANTHROPIC_API_KEY` for Claude Engineer.
+- Optional `E2B_API_KEY` if you use Claude Engineer features that call E2B.
+
+Do not paste these keys into source files. Add them as Daytona workspace
+environment variables or local environment variables that the Dev Container can
+forward into the workspace.
+
+## Step 1: Open Omni Engineer in Daytona
+
+Start with the Omni Engineer repository:
+
+```bash
+git clone https://github.com/Doriandarko/omni-engineer.git
+cd omni-engineer
+```
+
+The Dev Container configuration for this workflow uses the Python 3.11 base
+image, installs the repository dependencies from `requirements.txt`, and passes
+`OPENROUTER_API_KEY` through the workspace environment. When Daytona opens the
+workspace, the dependencies are installed without requiring a private `.env`
+file in the repository.
+
+After the workspace is ready, launch Omni Engineer:
+
+```bash
+python omni-eng.py
+```
+
+Use Omni Engineer for broad repository mapping. It is useful for asking, "Which
+files define the command this README describes?" or "Which setup steps are
+mentioned in documentation but not present in the project files?"
+
+## Step 2: Open Claude Engineer in Daytona
+
+Open a second workspace for Claude Engineer:
+
+```bash
+git clone https://github.com/Doriandarko/claude-engineer.git
+cd claude-engineer
+```
+
+The Dev Container configuration installs `uv`, creates a virtual environment,
+and installs the dependencies from `requirements.txt`. It forwards
+`ANTHROPIC_API_KEY` and optional `E2B_API_KEY` from the workspace environment.
+That keeps the repo safe to fork and review because no credentials are committed.
+
+Launch the CLI when you want a terminal review loop:
+
+```bash
+uv run ce3.py
+```
+
+Or launch the web interface when you want a browser-based review surface:
+
+```bash
+uv run app.py
+```
+
+Use Claude Engineer for the second pass. Its job is not to repeat the same map
+that Omni Engineer produced. Its job is to review the patch as if it were going
+to a maintainer: is the corrected command accurate, is the README still clear,
+and are the release notes honest about what changed?
+
+## Step 3: Clone the docs-drift demo
+
+Use the demo repository as a safe practice target:
+
+```bash
+git clone https://github.com/rohitmulani63-ops/daytona-docs-drift-demo.git
+cd daytona-docs-drift-demo
+git checkout docs-drift-start
+```
+
+The `docs-drift-start` branch intentionally contains a stale README command.
+The package exposes a console script named `docs-drift-demo`, but the README
+points to an older `python run.py --serve` command. This is a small example, but
+it mirrors a common production problem: code changed, documentation did not.
+
+Ask Omni Engineer to inspect the repository with a focused prompt:
+
+```text
+Read README.md, pyproject.toml, src/docs_drift_demo/cli.py, and docs/release-readiness.md.
+Find any command in the README that does not match the package entry points.
+Suggest the smallest documentation patch and explain why it is enough.
+```
+
+A good first-pass answer should identify the stale command, point to the current
+entry point in `pyproject.toml`, and recommend updating the README to use the
+real command.
+
+## Step 4: Patch the smallest useful thing
+
+The goal is not to rewrite the whole README. The goal is to make the next user
+successful. Patch the stale start command so it matches the package entry point:
+
+```bash
+docs-drift-demo --status
+```
+
+Then update the release-readiness notes with the file changed, the corrected
+command, and the review checks you expect a maintainer to perform. Keep the
+notes short. A reviewer should be able to scan them in under a minute.
+
+This is where Daytona helps. Because the workspace starts from a clean clone,
+you are less likely to depend on a package, path, or environment variable that
+only exists on your own machine.
+
+## Step 5: Ask Claude Engineer to review the repair
+
+Move to the Claude Engineer workspace and give it the patch context. Keep the
+prompt narrow:
+
+```text
+Review this docs-drift patch before it becomes a PR.
+Check whether the README command matches pyproject.toml and cli.py.
+Check whether docs/release-readiness.md records the corrected command clearly.
+Do not rewrite unrelated sections. Return risks, missing checks, and a final go/no-go.
+```
+
+The review should look for three things:
+
+- **Correctness**: the new command exists and matches the code.
+- **Scope control**: the patch does not rewrite unrelated documentation.
+- **Release clarity**: the notes explain what changed and how to check it.
+
+If Claude Engineer suggests broad rewrites, push back. Maintainers usually prefer
+small, reviewable documentation patches over sweeping prose changes.
+
+## Step 6: Turn the workflow into a pull request
+
+When both AI engineering passes agree on the fix, prepare the PR. A useful PR
+body for docs drift has four parts:
+
+```markdown
+## Summary
+- Correct the stale README start command.
+- Record the docs-drift repair in release-readiness notes.
+
+## Why
+The old command no longer matches the package entry point in pyproject.toml.
+
+## Review notes
+- Omni Engineer mapped README.md to pyproject.toml and cli.py.
+- Claude Engineer reviewed the patch for scope and release clarity.
+
+## Checks
+- Confirmed the documented command matches the package entry point.
+```
+
+That structure tells the maintainer what changed, why it changed, and how the AI
+assistants were used without dumping private transcripts into the PR.
+
+## Common issues and troubleshooting
+
+**Problem:** The Dev Container starts, but Omni Engineer cannot call a model.
+
+**Solution:** Check that `OPENROUTER_API_KEY` is set in the Daytona workspace
+environment. Do not create a committed `.env` file with the key.
+
+**Problem:** Claude Engineer starts, but the web interface cannot use Anthropic.
+
+**Solution:** Check that `ANTHROPIC_API_KEY` is available in the workspace
+environment. If you are using optional tools, check whether those tools require
+additional keys such as `E2B_API_KEY`.
+
+**Problem:** The AI assistant suggests rewriting the whole README.
+
+**Solution:** Narrow the prompt. Ask for the smallest patch that makes the
+failing command reproducible. Docs-drift repair is a precision task, not a style
+rewrite.
+
+**Problem:** The reviewer asks for proof that the command works.
+
+**Solution:** Add a short release-readiness note that names the corrected command
+and the files checked. If the repository has tests or a CLI smoke command, run
+those checks in the Daytona workspace before updating the PR.
+
+## Why this workflow works
+
+The two-agent split keeps the work disciplined. Omni Engineer is responsible for
+mapping the mismatch. Claude Engineer is responsible for reviewing the proposed
+repair. Daytona is the reproducible workspace around both tools. That separation
+matters because documentation drift is often caused by hidden local context. A
+clean workspace removes much of that hidden context before the PR reaches a
+maintainer.
+
+This pattern also scales. Use it for onboarding docs, install guides, SDK
+examples, API migration notes, internal runbooks, and release checklists. The
+best fixes are usually small: one corrected command, one missing environment
+variable, one renamed script, or one clarified setup step.
+
+## Conclusion
+
+Docs drift wastes developer time because it looks trustworthy until someone
+tries to follow it. A Daytona workspace gives you a clean place to reproduce the
+problem. Omni Engineer helps map the mismatch. Claude Engineer reviews the patch
+before it becomes public. Together, they create a practical review loop for
+shipping documentation that still matches the code.
+
+The important habit is restraint. Do not ask AI to rewrite everything. Ask it to
+find the promise the documentation makes, compare that promise with the code,
+and repair the smallest useful piece. That is how AI engineering becomes useful
+to maintainers instead of noisy for them.
+
+## References
+
+- [Daytona](https://www.daytona.io/)
+- [Omni Engineer](https://github.com/Doriandarko/omni-engineer)
+- [Claude Engineer](https://github.com/Doriandarko/claude-engineer)
+- [Dev Containers specification](https://containers.dev/)
+- [Docs Drift Repair](/definitions/docs-drift-repair.md)