doc-updater

name	doc-updater
description	Detect changes that require documentation updates and suggest/execute updates. Use when code changes may impact documentation, during pre-PR creation checklist, or when explicitly requested. Use when this capability is needed.
metadata	{"author":"drillan"}

doc-updater

Detect changes that require documentation updates and suggest/execute updates.

Overview

This skill prevents documentation update oversights when code changes occur. It detects API changes, configuration option additions, feature additions, etc., and suggests updates to related READMEs, API specs, configuration guides, and more.

Trigger

• When code changes may impact documentation
• When user explicitly requests documentation updates
• During pre-PR creation checklist execution

Instructions

Step 1: Analyze Changes

Analyze changes to determine documentation impact:

# Get changed files
git diff --name-only HEAD~1

# Get detailed diff
git diff HEAD~1

Step 2: Identify Documentation Impact

Detect the following patterns:

Change Type	Documentation Impact
New CLI option	--help output, README
API endpoint added/changed	API documentation
Configuration option added	Config guide
Environment variable added	Setup guide
Feature added	Feature documentation
Breaking change	Migration guide, CHANGELOG

Step 3: Find Related Documents

# Find documentation files
find . -name "*.md" -type f
find . -name "README*" -type f
find docs/ -type f 2>/dev/null

Identify documentation locations:

• README.md - Project overview
• docs/ - Detailed documentation
• CHANGELOG.md - Change history
• API.md - API specification
• CONTRIBUTING.md - Contribution guide

Step 4: Generate Update Suggestions

Generate update suggestions based on change type:

CLI Option Added

## Documentation Update Suggestion

### README.md
Add description for `--new-option` option:

```diff
+ ### New Option
+ Use `--new-option` to enable the new feature.

Configuration Change

## Documentation Update Suggestion

### docs/configuration.md
Add new configuration option:

```diff
+ ## new_setting
+
+ Type: `boolean`
+ Default: `false`
+
+ Enables the new feature.

Step 5: Execute Updates

After user approval, update documentation:

1. Edit target files
2. Stage changes
3. Preview changes

# Stage documentation changes
git add README.md docs/

Detection Rules

Auto-detect Patterns

# CLI options
r"add_argument\s*\(\s*['\"]--(\w+)"
r"Option\s*\(\s*['\"]--(\w+)"
r"typer\.Option\("

# API endpoints
r"@(app|router)\.(get|post|put|delete|patch)"
r"def\s+\w+\s*\(.*request"

# Configuration
r"Config\s*\("
r"settings\.\w+"
r"os\.environ\.get\("

# Environment variables
r"getenv\s*\(\s*['\"](\w+)"
r"environ\[.(\w+).\]"

Changelog Detection

Suggest CHANGELOG updates for the following changes:

• Breaking changes (API signature changes)
• New features
• Bug fixes
• Security patches

Output Format

Documentation Impact Report

## Documentation Update Check

### Detected Changes
| Type | Impact | Target Document |
|------|--------|-----------------|
| CLI option added | `--format` | README.md |
| Environment variable added | `API_KEY` | docs/setup.md |
| API change | `/users` endpoint | docs/api.md |

### Recommended Actions
1. Add description of new option to README.md
2. Add environment variable setup instructions to docs/setup.md
3. Reflect endpoint changes in docs/api.md

Execute updates? [y/N]

Success

✅ Documentation updated

Updated files:
  - README.md (+15 lines)
  - docs/setup.md (+8 lines)
  - CHANGELOG.md (+5 lines)

Next step:
  git commit -m "docs: update documentation for new features"

Error Handling

Error	Action
No docs found	ℹ️ No documentation files found
Doc not writable	⚠️ No write permission for file
Pattern not found	Suggest manual verification

Integration

This skill integrates with:

1. code-quality-gate - Documentation check before commit
2. issue-reporter - Report documentation update progress
3. PR Template - Documentation update checklist

Best Practices

1. Update with code changes - Don't postpone documentation updates
2. Clarify change scope - Specifically describe what changed
3. Include examples - Add code examples and usage examples
4. Maintain CHANGELOG - Record important changes in history

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.