Automated Documentation Updates

Documentation drift is the silent killer of developer productivity. Code changes but docs do not, creating a growing gap between what the code does and what the docs say. Automated documentation updates close this gap by triggering Gemini analysis whenever source files change. The CI job compares the current docs against the current code, identifies discrepancies, and either generates updated docs or flags the gaps for human attention.

The safest pattern is documentation suggestion, not documentation generation. A CI job that generates docs and auto-commits them risks introducing incorrect information. A CI job that identifies outdated docs and posts a PR comment saying "src/auth.ts changed but docs/auth.md was not updated — here is a suggested update" is more valuable because it preserves human oversight while reducing the effort of keeping docs current.

#!/bin/bash
# Detect documentation drift and suggest updates
set -euo pipefail

CHANGED_SRC=$(git diff --name-only origin/main...HEAD -- 'src/**/*.ts')
DRIFT_REPORT=""

for src_file in $CHANGED_SRC; do
  # Derive expected doc path
  doc_file="docs/$(basename "$src_file" .ts).md"

  if [ ! -f "$doc_file" ]; then
    DRIFT_REPORT+="\n- **$src_file** has no documentation at $doc_file"
    continue
  fi

  # Check if doc was updated in this PR
  if ! git diff --name-only origin/main...HEAD | grep -q "$doc_file"; then
    # Generate suggested update
    SUGGESTION=$(gemini -p "Compare this source code with its documentation. Identify what changed in the code that is not reflected in the docs. Output a concise list of required doc updates.\n\nSource:\n$(cat "$src_file")\n\nCurrent docs:\n$(cat "$doc_file")" 2>/dev/null)

    DRIFT_REPORT+="\n### $doc_file\n$SUGGESTION\n"
  fi
done

if [ -n "$DRIFT_REPORT" ]; then
  echo -e "## Documentation Drift Detected\n$DRIFT_REPORT" > drift-report.md
  gh pr comment "$PR_NUMBER" --body-file drift-report.md
fi