cotera

GitHub Documentation Sync Agent

Detect documentation drift in GitHub repos. Find code changes that outpaced their docs and open PRs to fix them.

Drift detectionDoc updatesAPI accuracyAutomated PRs

The Challenge

Documentation starts accurate and then slowly drifts. A developer adds a new API parameter but forgets the docs. Someone renames a config key but the README still references the old one. Over time, the docs become a liability — developers stop trusting them, new hires get confused, and customers file support tickets about instructions that don't work anymore.

What This Prompt Does

Read Code & Docs

Fetches both source files and documentation to build a mapping of what describes what

Detect Drift

Compares APIs, configs, and features against their documentation to find mismatches

Update Docs

Rewrites outdated sections to match current code while preserving style and tone

Open PR

Commits all documentation fixes to a branch and opens a PR with a detailed change summary

The Prompt

The Prompt

Task

Use @GitHub/Read FileName it "GitHub/Read File" and call it with @GitHub/Read File to read source code files and their corresponding documentation. Compare them to detect documentation drift — functions, APIs, configs, or features that have changed in code but not in the docs. Update outdated documentation, create a branch, commit the changes, and open a PR using @GitHub/Get Branch SHAName it "GitHub/Get Branch SHA" and call it with @GitHub/Get Branch SHA, @GitHub/Create BranchName it "GitHub/Create Branch" and call it with @GitHub/Create Branch, @GitHub/Update FileName it "GitHub/Update File" and call it with @GitHub/Update File, and @GitHub/Create Pull RequestName it "GitHub/Create Pull Request" and call it with @GitHub/Create Pull Request.

Input

The user provides:

  1. The repository owner and name (e.g., "acme/web-app")
  2. The scope of the audit (e.g., "API docs", "README", "all docs", specific files)
  3. Key source files to compare against (optional, e.g., "src/api/routes.ts should match docs/api.md")
  4. The base branch (optional, defaults to "main")

Example: "Check if the README in acme/api still matches the actual API routes in src/routes/"

Context

Read Source Code and Documentation

  1. Use @GitHub/Read FileName it "GitHub/Read File" and call it with @GitHub/Read File to fetch documentation files (README.md, docs/, wiki pages, inline comments)
  2. Use @GitHub/Read FileName it "GitHub/Read File" and call it with @GitHub/Read File to fetch the corresponding source code files
  3. Build a mapping of which docs describe which code areas

Detect Documentation Drift

  1. API endpoints: Compare documented routes, parameters, and response shapes against actual route definitions
  2. Configuration options: Compare documented config keys and defaults against actual config schemas or .env.example
  3. Function signatures: Compare documented function parameters and return types against actual code
  4. Installation/setup steps: Verify documented commands still work with current package.json scripts and dependencies
  5. Feature descriptions: Check if documented features still exist and work as described

Categorize Issues

  1. Stale docs: Documentation that describes something that no longer exists
  2. Missing docs: Code that has been added with no corresponding documentation
  3. Inaccurate docs: Documentation that exists but describes behavior incorrectly
  4. Outdated examples: Code examples in docs that use old API patterns or deprecated methods

Update Documentation

  1. Rewrite outdated sections to match current code behavior
  2. Add documentation for undocumented features or APIs
  3. Remove references to deleted features
  4. Update code examples to use current patterns
  5. Preserve the existing documentation style and tone

Create Branch and PR

  1. Use @GitHub/Get Branch SHAName it "GitHub/Get Branch SHA" and call it with @GitHub/Get Branch SHA to get the current SHA of the base branch
  2. Use @GitHub/Create BranchName it "GitHub/Create Branch" and call it with @GitHub/Create Branch to create a new branch (e.g., "docs/sync-api-documentation")
  3. Use @GitHub/Update FileName it "GitHub/Update File" and call it with @GitHub/Update File to commit the updated documentation files
  4. Use @GitHub/Create Pull RequestName it "GitHub/Create Pull Request" and call it with @GitHub/Create Pull Request to open a PR with a detailed summary of all documentation changes

Output

Documentation Sync Report:

Repository: [owner/repo] Files Analyzed: [count] source files, [count] doc files

Drift Detected:

| Doc File | Issue Type | Description | |----------|-----------|-------------| | [docs/api.md] | Inaccurate | [endpoint X returns different fields than documented] | | [README.md] | Stale | [references removed feature Y] | | [docs/config.md] | Missing | [new config option Z not documented] |

Changes Made:

  • Updated [file1] - [summary of changes]
  • Updated [file2] - [summary of changes]

Pull Request: [PR URL] Status: Ready for review

Remaining Items (Manual Review Needed):

  • [Items that require human judgment to resolve]

Example Usage

Try asking:

  • →"Check if the README in acme/api still matches the actual API routes"
  • →"Audit docs/configuration.md against the current .env.example and config schema"
  • →"Find all undocumented API endpoints in acme/web-app and update the docs"