---
name: update-docs
version: "1.0"
description: Detects documentation files that have become stale due to code changes and applies targeted updates. Use when implementing features, fixing bugs, or refactoring code that may invalidate existing docs. Relevant for any repository with in-repo documentation.
---

# 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.

## When to Activate

- After implementing a feature or bug fix, before creating a PR
- When code changes rename, remove, or change the behavior of public APIs
- When the user says "update docs", "check docs", or "are the docs stale"
- When new code adds features, fields, or APIs that existing docs should reference
- After refactoring that changes function signatures, config keys, or CLI flags
- When reviewing a branch and noticing documentation may be out of date

## Process

Follow these steps in order. Do not skip steps.

### 1. Get the diff

```bash
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:

```bash
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:

```bash
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

Go through **every** changed file in the PR. For each file, extract
identifiers from the modified lines (lines starting with `+` or `-`)
and from diff hunk headers (`@@` lines). Write them down as a numbered
checklist — one entry per changed file, with all identifiers from that
file.

Use the most specific form of each identifier. CLI flag names,
configuration keys, full function names, and type names are good —
they match only relevant docs. Avoid generic short words that would
match hundreds of unrelated files. If a generic term is the only
identifier available for a change, include it, but prefer specific
forms when they exist.

Do not skip files. Do not prioritize some files over others. Every
changed file gets an entry in the checklist.

### 4. Search docs for every identifier

Write a shell script that takes the identifiers from step 3 and
greps for each one across the documentation files from step 2.
Run the script in a single Bash call:

```bash
for id in "identifier1" "identifier2" "identifier3"; do
  matches=$(grep -rlFi "$id" <doc_files> 2>/dev/null)
  if [ -n "$matches" ]; then
    echo "MATCH: $id -> $matches"
  fi
done
```

Include every identifier from every checklist entry in the `for`
loop. The script handles the searching mechanically — no identifiers
are skipped.

From the script output, collect all matched doc files into a
candidate list.

### 5. Evaluate candidates (two passes)

**Pass 1 — Quick scan.** For each candidate, view only the lines
that matched the grep (use `grep -n` to see them in context). Based
on the matching lines alone, give a quick verdict:

```
- path/to/doc.md -> possibly stale (describes behavior that changed)
- path/to/other.md -> not stale (mentions identifier in passing)
```

Every candidate must have a verdict. Do not skip candidates.

**Pass 2 — Deep read.** Only for candidates marked "possibly stale"
in pass 1. Read the full file alongside the relevant section of the
diff. Confirm whether the doc is actually stale. Check the file
header for auto-generation markers — if the file is generated from
source, skip it.

When evaluating:

- **Only flag docs whose content is now incorrect.** A doc that
  mentions an identifier is not stale if the described behavior is
  unchanged. It is stale only if the behavior, signature, or semantics
  changed in a way that makes the doc misleading.
- **Do not flag changelog entries or release notes that describe past
  releases.** Historical entries are not stale because the code evolved.

### 6. Review beyond grep results

This step catches stale references that grep cannot find because
documentation often uses prose names that differ from code identifiers,
and new code introduces identifiers that don't exist in any doc yet.

Always read the repository's README. Also read any main index or
overview files at the root of doc directories. Read each file fully
and compare it against the diff. Determine whether it describes any
behavior, flow, or feature that the code changes affected. If it
does, add it to the list of confirmed stale docs.

Also scan the discovered documentation files for any that may cover
the same area as the changed code, based on your understanding of
what the diff does. You don't need to read every file — use file
names and paths to decide which ones are worth checking.

### 7. Update confirmed stale docs

For each doc confirmed stale:

1. Read the full file
2. Update the documentation so it accurately reflects the new code
3. Preserve the file's existing format, style, and structure

### 8. Commit changes

If any documentation files were updated:

```bash
git add <updated_doc_files>
git commit -m "[TICKET_KEY] docs: update documentation for code changes"
```

Replace TICKET_KEY with the actual ticket key from the task context.

### 9. Output

If docs were updated:
```
DOCS_UPDATED

Updated:
- [path/to/doc.md] Brief description of what was updated and why
- [path/to/other.rst] Brief description
```

If no docs needed updating:
```
NO_DOCS_UPDATED
```

If no doc files found:
```
NO_DOCS_FOUND
```

## Constraints

- **Only change what the diff affects.** Fix stale content and add
  new information that the diff introduced to existing docs. Do not
  improve, restructure, or reformat documentation that is unrelated
  to the code change.
- **Do not update historical entries.** Changelog and release note
  entries for past releases are not stale — they describe what happened
  at that point in time.
- **Skip auto-generated files.** Do not edit files that are generated
  from source. They should be regenerated, not manually patched.
- **Update existing files only.** Do not create new doc files from
  scratch.
- **Preserve format.** Match the existing file's formatting conventions
  (heading style, list style, code block syntax, etc.).