{"slug": "your-documentation-is-out-of-date-let-an-ai-agent-keep-it-in-sync", "title": "Your Documentation Is Out of Date. Let an AI Agent Keep It in Sync", "summary": "A developer has proposed a `sync-docs` agent skill that keeps technical Markdown documentation aligned with source code by storing a `commit` and `updated` date in each document's frontmatter. The agent uses the recorded commit as a baseline, inspects everything changed since then, and reviews the existing documentation against the current implementation rather than simply appending Git summaries. The approach treats source code as the source of truth and aims for accuracy over activity.", "body_md": "We've all been there.\n\nYou join a new team, open the repository, and find a beautifully written `README.md`, an architecture document, and a collection of Markdown files explaining how everything works.\n\nYou start reading.\n\nA few minutes later, you notice that the architecture diagram doesn't match the actual implementation. The documentation references tools that no longer exist. Some configuration options have changed, and a few important components are missing entirely.\n\nThe documentation is there, but can you trust it?\n\nThis is one of the most common problems in software engineering: **documentation slowly drifts away from the source code.**\n\nAnd it's not because developers don't understand the importance of documentation. It's because maintaining it is a continuous task, and it's very easy to forget.\n\nBut what if we could delegate this responsibility to an AI agent?\n\nLet's start with one simple principle:\n\n**The source code is always the source of truth.**\n\nDocumentation is a human-friendly representation of how the system works. It helps developers understand the architecture, discover available tools, learn conventions, and onboard new team members.\n\nBut documentation should never override the implementation.\n\nWhenever the implementation changes, the relevant documentation should be reviewed and updated if necessary.\n\nThe problem is knowing when documentation needs attention.\n\nHere's a simple trick.\n\nWhat if every technical Markdown document included metadata describing the last commit against which it was reviewed?\n\nFor example:\n\n```\n---\ncommit: '9b6f166af5227ff4093af7347084d8f7d2a81e4f'\nupdated: '2026-11-04'\n---\n```\n\nThat's it.\n\nTwo simple pieces of information:\n\n`commit`: The Git commit against which the document was last reviewed and synchronized.`updated`: The date the document was last reviewed.\nThis small addition gives us something very useful: a reference point.\n\nWhen someone opens a Markdown document, they can immediately see when it was last reviewed and how far behind the codebase that review was.\n\nMore importantly, an AI agent can use that commit as a starting point for reviewing the document.\n\nFor example, if the document references commit `9b6f166`, the agent can inspect everything that has changed since that commit and determine whether any of those changes affect the documentation.\n\nWe now have a simple, explicit relationship between our documentation and the source code.\n\n`sync-docs` skill\nImagine having an agent skill called `sync-docs`.\n\nIts responsibility is straightforward:\n\n**Make sure technical documentation accurately reflects the current state of the codebase.**\n\nThe workflow could look something like this:\n\nFor example, the agent might discover that since the last documentation review:\n\nIt can then inspect the relevant source files and update the documentation accordingly.\n\nNotice something important: the agent isn't simply summarizing the latest Git changes and appending them to a document.\n\nIt needs to understand the existing documentation, inspect the current implementation, and determine whether the document still accurately describes the system.\n\nThe goal is accuracy, not just activity.\n\nLet's make this concrete.\n\nWe need two things:\n\nThe important distinction is that the skill owns the logic. The workflow simply orchestrates it.\n\nLet's create the following structure:\n\n```\n.agents/\n  skills/\n    sync-docs/\n      SKILL.md\n```\n\nThe `SKILL.md` file contains the actual instructions the agent must follow.\n\nHere is an example implementation:\n\n`.agents/skills/sync-docs/SKILL.md`\n\n```\n---\nname: sync-docs\ndescription: Review and synchronize Markdown\n  documentation against the current source code.\n---\n\n# Sync Documentation\n\nYour responsibility is to ensure that technical\ndocumentation accurately reflects the current\nimplementation in the repository.\n\nThe source code is always the source of truth.\n\n## 1. Discover documentation\n\nFind all Markdown files containing the following\nfrontmatter fields:\n\n- commit\n- updated\n\nThese fields identify the last source-code commit\nagainst which the document was reviewed.\n\nIgnore files without this metadata.\n\n## 2. Review each document\n\nFor every document:\n\n1. Read its recorded commit.\n2. Verify that the commit exists in the repository.\n3. Identify the source files relevant to the\n   document.\n4. Inspect changes introduced since the recorded\n   commit:\n\n   git diff <recorded-commit>..HEAD\n\n5. Inspect the current implementation of the\n   affected components.\n6. Determine whether the documentation still\n   accurately describes the implementation.\n\nDo not assume that every code change requires\na documentation change.\n\n## 3. Update documentation\n\nWhen documentation is outdated:\n\n- Update incorrect descriptions.\n- Add missing architectural information.\n- Remove references to obsolete tools,\n  components or configuration.\n- Update examples that no longer match\n  the implementation.\n- Preserve useful explanations and the\n  existing writing style.\n\nNever invent implementation details.\n\nNever modify application source code.\n\n## 4. Update synchronization metadata\n\nAfter successfully reviewing a document,\nupdate its frontmatter:\n\ncommit: <current HEAD commit>\nupdated: <current date>\n\nThe commit must represent the exact source-code\nrevision that was reviewed.\n\nIf the review cannot be completed confidently,\ndo not advance the metadata.\n\nIf the document is already accurate, its content\ndoes not need to change, but its review metadata\nshould still be updated.\n\n## 5. Report findings\n\nAt the end, provide a summary containing:\n\n- Documents reviewed.\n- Documents updated.\n- Documents already accurate.\n- Documents that could not be reviewed.\n- Architectural inconsistencies discovered.\n- Potential bugs or unexpected implementation\n  changes worth investigating.\n\nDo not fix application code or architectural\nissues as part of this task.\n\nLeave those findings for human review.\n```\n\nThat's the entire skill.\n\nThe interesting thing is that it doesn't know anything about GitHub, pull requests, or scheduling. It only knows how to perform one job: keep documentation synchronized with the source code.\n\nThis makes it reusable. You can invoke it manually from your coding agent whenever you want:\n\nUse the sync-docs skill to review and synchronize the technical documentation in this repository.\n\nOr you can use it as part of a larger agent workflow.\n\nNow let's automate it.\n\nCreate the following file:\n\n```\n.github/\n  workflows/\n    sync-docs.md\n```\n\nThe workflow is intentionally simple. It doesn't contain any documentation synchronization instructions because those already live in our skill.\n\nIts only responsibility is to invoke the skill and create a PR with the results.\n\n`.github/workflows/sync-docs.md`\n\n```\n---\nname: Sync Documentation\n\non: weekly on monday\n\npermissions:\n  contents: read\n  pull-requests: read\n\nsafe-outputs:\n  create-pull-request:\n    title-prefix: \"[docs-sync] \"\n    labels:\n      - documentation\n    allowed-files:\n      - docs/**\n      - README.md\n---\n\n# Synchronize Technical Documentation\n\nYour task is to maintain the technical\ndocumentation in this repository.\n\n## Instructions\n\n1. Read and follow the skill located at:\n\n   `.agents/skills/sync-docs/SKILL.md`\n\n2. Invoke the `sync-docs` skill and let it\n   perform the complete documentation review.\n\n3. Inspect the resulting changes and findings.\n\n4. If documentation or synchronization\n   metadata has changed, create a pull\n   request containing:\n\n   - The updated Markdown documents.\n   - A summary of documents reviewed.\n   - A summary of documentation changes.\n   - Any architectural inconsistencies or\n     potential issues discovered.\n\n5. If there are no changes to propose,\n   do not create an empty pull request.\n\n## Important\n\nNever merge pull requests automatically.\n\nAll documentation changes must be reviewed\nand approved by a human.\n\nDo not modify application source code.\n```\n\nThe workflow uses a scheduled trigger, invokes our reusable skill, and creates a PR when there are changes to propose.\n\nNotice how little logic the workflow contains. That's intentional.\n\nWe don't want to maintain two implementations of the same process.\n\nThe skill defines *how* documentation is synchronized. The workflow defines *when* it happens and *what to do with the results*.\n\nGitHub Agentic Workflows can compile these Markdown workflow definitions into standard GitHub Actions workflow files using the `gh aw` CLI:\n\n```\ngh extension install github/gh-aw\ngh aw compile\n```\n\nThe compilation generates a `.lock.yml` workflow alongside the Markdown source. You commit both files to the repository.\n\nYou can choose a different schedule, such as every two weeks or once a month, depending on how quickly your codebase evolves.\n\nFor more information, see the [GitHub Agentic Workflows documentation](https://github.github.com/gh-aw/).\n\n*Note: The example assumes that the selected agent runtime supports the skill format and that the skill is available in its execution environment. The workflow must be configured to load and invoke it; simply referencing a file path does not automatically execute a skill.*\n\nImagine a PR created by the workflow:\n\n**Title: `[docs-sync] Synchronize architecture and tooling documentation`**\n\nIt might contain:\n\n| Document | Result | \n|---|---|\n| `docs/architecture.md` | Updated service dependencies | \n| `docs/development-tools.md` | Removed obsolete CLI reference | \n| `docs/deployment.md` | Reviewed, no content changes needed | \n| `docs/api.md` | Updated endpoint descriptions | \n\nThe PR description could also highlight findings that deserve attention:\n\nThis is where things get particularly interesting.\n\nThe PR is no longer just a documentation update. It becomes another opportunity for the engineering team to inspect the system and discover things that might otherwise go unnoticed.\n\n**We are using AI to maintain documentation, but we're also using documentation reviews to improve the quality of the software itself.**\n\nA timestamp tells us when something happened.\n\nA Git commit tells us exactly which version of the source code was reviewed.\n\nThis distinction is important.\n\nSuppose a document was last reviewed two weeks ago. During those two weeks, the codebase might have changed significantly, or perhaps nothing relevant to that document changed at all.\n\nWith a commit reference, the agent can inspect the actual changes rather than guessing based on the document's age.\n\nIt also makes the process incremental.\n\nThe agent doesn't need to rediscover the entire history of the project every time it runs. It can start from the last reviewed commit and investigate what happened since then.\n\nOf course, the commit reference is not a guarantee that the document is accurate. It's a record of the last successful review. The quality of that review still matters.\n\nThere is one important detail here: **the workflow should open pull requests, never merge documentation updates automatically.**\n\nWhy?\n\nBecause reviewing these PRs is valuable in itself.\n\nImagine the agent updating an architecture document because it discovered that a service behaves differently from what the documentation describes.\n\nDuring the review, a developer might realize that the implementation has drifted from the intended architecture.\n\nOr perhaps the agent discovers an undocumented configuration change, an unexpected dependency, or a tool that is no longer being used.\n\nThese are useful signals.\n\nA documentation synchronization PR can become an opportunity to spot architectural inconsistencies, accidental complexity, missing documentation, and even potential bugs.\n\nThe agent does the investigation and proposes the updates. Developers review the changes, challenge the findings, and decide whether to merge them.\n\nThis keeps humans in the loop while making the maintenance process much less painful.\n\nThere are some important details to get right when implementing this.\n\n**1. Only update the commit after a successful review**\n\nThe commit in the frontmatter should represent the latest code version actually reviewed, not simply the latest HEAD.\n\nIf the agent fails to inspect a document or cannot confidently determine whether it is accurate, it shouldn't silently advance the commit reference.\n\n**2. Don't change documentation just for the sake of changing it**\n\nIf the source code changes but the documentation remains accurate, there is no reason to modify the document's content.\n\nThe agent can still update its review metadata to record that the document has been checked against the newer commit.\n\n**3. Never merge automatically**\n\nAlways open a pull request and let a developer review it.\n\nApart from preventing incorrect documentation updates from reaching the main branch, these reviews can expose problems that might otherwise go unnoticed.\n\n**4. Make the review scope explicit**\n\nNot every Markdown file needs to describe the entire codebase.\n\nAn architecture document might depend on changes across multiple services, while a tool reference might only depend on a particular directory.\n\nThe skill should use the document's content to determine which parts of the repository are relevant.\n\n**5. Handle invalid or unavailable commits gracefully**\n\nA document might reference a commit that is no longer available locally, or a commit that doesn't exist in the current repository history.\n\nThe agent shouldn't guess where to start. It should flag the document for human investigation rather than silently replacing its reference.\n\nI particularly like this idea because it changes how we think about documentation.\n\nToday, documentation is often treated as something we write when we create a feature, launch a project, or onboard a new developer.\n\nThen it slowly gets forgotten.\n\nBut documentation should be treated more like code: something that needs continuous maintenance.\n\nWe already have automated tests, linters, formatters, dependency updates, and security scans running against our repositories.\n\nWhy shouldn't documentation have its own maintenance workflow?\n\nWith a small piece of metadata, a reusable AI skill, and a scheduled GitHub workflow, we can make documentation maintenance a continuous process rather than an occasional cleanup exercise.\n\nAnd there's an additional benefit: every synchronization PR gives the team another opportunity to inspect the system, question architectural decisions, and spot inconsistencies.\n\n**Your source code evolves. Your documentation should evolve with it.**\n\nAnd perhaps the best part is that the next developer joining your team won't have to wonder whether the architecture document they're reading is describing the system you actually have today.\n\nThey can see when it was last reviewed, what version of the code it was checked against, and trust that the team has a process for keeping it up to date.", "url": "https://wpnews.pro/news/your-documentation-is-out-of-date-let-an-ai-agent-keep-it-in-sync", "canonical_source": "https://dev.to/remojansen/your-documentation-is-out-of-date-let-an-ai-agent-keep-it-in-sync-5fba", "published_at": "2026-11-04 22:06:10+00:00", "updated_at": "2026-11-04 22:23:53.259679+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "artificial-intelligence"], "entities": [], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/your-documentation-is-out-of-date-let-an-ai-agent-keep-it-in-sync", "markdown": "https://wpnews.pro/news/your-documentation-is-out-of-date-let-an-ai-agent-keep-it-in-sync.md", "text": "https://wpnews.pro/news/your-documentation-is-out-of-date-let-an-ai-agent-keep-it-in-sync.txt", "jsonld": "https://wpnews.pro/news/your-documentation-is-out-of-date-let-an-ai-agent-keep-it-in-sync.jsonld"}}