diff --git a/authors/rohit_m.md b/authors/rohit_m.md new file mode 100644 index 00000000..c433ceed --- /dev/null +++ b/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. diff --git a/definitions/20260619_definition_docs_drift_repair.md b/definitions/20260619_definition_docs_drift_repair.md new file mode 100644 index 00000000..9ae9791f --- /dev/null +++ b/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. diff --git a/guides/20260619_repair_docs_drift_with_omni_and_claude_engineer_in_daytona.md b/guides/20260619_repair_docs_drift_with_omni_and_claude_engineer_in_daytona.md new file mode 100644 index 00000000..8739fb42 --- /dev/null +++ b/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) diff --git a/guides/assets/20260619_repair_docs_drift_with_omni_and_claude_engineer_in_daytona_workflow.svg b/guides/assets/20260619_repair_docs_drift_with_omni_and_claude_engineer_in_daytona_workflow.svg new file mode 100644 index 00000000..5696a6a3 --- /dev/null +++ b/guides/assets/20260619_repair_docs_drift_with_omni_and_claude_engineer_in_daytona_workflow.svg @@ -0,0 +1,36 @@ + + Docs drift repair workflow in Daytona + A Daytona workspace connects Omni Engineer, Claude Engineer, a demo repository, and a reviewed documentation patch. + + + Docs drift repair inside Daytona + Map the mismatch, patch the docs, review the release path, and keep secrets outside the repo. + + + Daytona + workspace + + Omni Engineer + maps docs drift + + Claude Engineer + reviews patch + + Ready + PR + + Demo repo: mismatched command becomes corrected documentation + + + + + + + + + + + + + +