# GitHub Documentation Sync Agent

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

Source: https://cotera.co/solutions/ops/github-documentation-sync

---

- **Team:** Operations
- **Tools:** GitHub
- **Difficulty:** advanced
- **Setup time:** 15 min
- **Time saved:** 2-3 hrs/week

## How it works
1. **Read Code & Docs** — Fetches both source files and documentation to build a mapping of what describes what
2. **Detect Drift** — Compares APIs, configs, and features against their documentation to find mismatches
3. **Update Docs** — Rewrites outdated sections to match current code while preserving style and tone
4. **Open PR** — Commits all documentation fixes to a branch and opens a PR with a detailed change summary

## Example requests
- 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

## Prompt

```markdown
## Task

Use @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 SHA, @GitHub/Create Branch, @GitHub/Update File, and @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 File to fetch documentation files (README.md, docs/, wiki pages, inline comments)
2. Use @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 SHA to get the current SHA of the base branch
2. Use @GitHub/Create Branch to create a new branch (e.g., "docs/sync-api-documentation")
3. Use @GitHub/Update File to commit the updated documentation files
4. Use @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]
```

## Related reading
- [GitHub vs GitLab: We Run Both. Here's What Each Actually Does Better.](https://cotera.co/articles/github-vs-gitlab-comparison.md)
- [GitHub vs Azure DevOps: One Evolved. The Other Didn't.](https://cotera.co/articles/github-vs-azure-devops-comparison.md)