update-docs

Update Docs

Code changes can silently invalidate documentation. A renamed function, a changed API signature, a removed configuration option, each can leave docs describing behavior that no longer exists. This skill detects that drift by matching the code diff against in-repo documentation and updating docs whose descriptions contradict the new code.

Process

Follow these steps in order. Do not skip steps.

1. Get the diff

DEFAULT_BRANCH=$(git rev-parse --abbrev-ref origin/HEAD | cut -d/ -f2)
git diff $(git merge-base HEAD "$DEFAULT_BRANCH")..HEAD --no-color

Record the list of files changed in the PR:

git diff --name-only $(git merge-base HEAD "$DEFAULT_BRANCH")..HEAD

If the diff is empty, output NO_DOCS_UPDATED and stop.

2. Discover documentation files

Explore the repository structure to identify where documentation lives. Different repos organize docs differently — look for dedicated doc directories, standalone files like README.md at any level, and any other files whose primary purpose is documentation.

Search broadly — include diagram and config files that live alongside docs:

find . -type f \( -name "*.md" -o -name "*.rst" -o -name "*.adoc" \
  -o -name "*.txt" -o -name "*.mmd" -o -name "*.puml" \
  -o -name "*.yaml" -o -name "*.yml" \) \
  ! -path "./.git/*" ! -path "./.forge/*" ! -path "./vendor/*" \
  ! -path "./node_modules/*" \
  | head -500

Then filter the results:

• Exclude files already modified in the PR (they are being actively updated — check against the changed file list from step 1)
• Exclude auto-generated files (lockfiles, generated API docs, swagger output)
• Exclude changelog and release note entries that describe past releases
• Exclude YAML/YML files that are not documentation. Only keep YAML files that live in doc directories or are clearly documentation examples.

If no documentation files exist in the repo, output NO_DOCS_FOUND and stop.

3. Build the identifier checklist