documentation-sync

Documentation Sync Skill

When to Trigger

Run after:

• A public API endpoint is added, changed, or removed
• A CLI command or flag is modified
• A new environment variable or config key is introduced
• A major component or module is refactored
• A new npm/pip/etc. package is added or removed from dependencies
• Any README.md reference becomes inaccurate

Step-by-Step Process

1. Identify What Changed

Review the git diff of the work just completed:

git diff main --name-only          # Files changed vs main
git diff HEAD~1 --name-only        # Files changed in last commit

Categorize changes:

• API changes → affects docs/api/, OpenAPI/Swagger specs, README.md
• Config changes → affects .env.example, docs/configuration.md
• Dependency changes → affects README.md (setup section), docs/getting-started.md
• Architecture changes → affects docs/architecture.md, diagrams
• New features → affects docs/features/, changelogs

2. Audit Existing Docs

For each affected category, check whether corresponding docs exist:

docs/
  api/             ← REST/GraphQL endpoint docs
  architecture.md  ← System design, component diagram
  configuration.md ← All env vars and config options
  getting-started.md ← Local setup guide
  features/        ← Per-feature descriptions
CHANGELOG.md       ← Version history
README.md          ← Project overview + quickstart

For each doc file that touches the changed area, read it and flag stale sections.

3. Update Docs — Priority Order

Update in this order (highest impact first):

A. README.md

• Setup instructions still accurate?
• Tech stack section reflects current stack?
• Any removed features still mentioned?

B. .env.example / Configuration Docs

For every new env variable added to code, add a corresponding entry:

# Description of what this does
NEW_VAR_NAME=example_value

Document in docs/configuration.md:

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| NEW_VAR_NAME | Yes | — | What it controls |

C. API Docs

For every endpoint change, update the relevant doc:

### POST /api/resource

**Changed in:** <date or version>
**Description:** ...
**Request Body:** ...
**Response:** ...
**Breaking Change:** Yes/No

D. CHANGELOG.md

Append an entry under ## [Unreleased]:

### Added
- <new feature description>

### Changed
- <what was modified and why>

### Fixed
- <bug fixed>

### Removed
- <what was removed>

Follow Keep a Changelog format.

E. Architecture Docs

If a new service, module, or significant component was added:

• Update the component list in docs/architecture.md
• Note any new external dependencies or integrations
• If a diagram exists (Mermaid, Draw.io), update it

4. Verify Internal Links

After editing, do a quick check for broken internal references:

# Find markdown links pointing to non-existent files
grep -r "\[.*\](.*\.md)" docs/ README.md | grep -v "http"

Manually verify the top 5 most-used internal links still resolve.

5. Report Changes

Output a summary:

## Documentation Sync Complete

**Files Updated:**
- README.md — updated setup section
- docs/configuration.md — added NEW_VAR_NAME
- CHANGELOG.md — added unreleased entry

**Files That May Need Manual Review:**
- docs/architecture.md — diagram may be outdated (manual update needed)

**No changes needed:**
- docs/api/ — no endpoint changes detected

Rules

• Never delete documentation without confirming with the user. Archive or mark as deprecated instead.
• Don't invent information. If you're unsure what a config variable does, write # TODO: document this and flag it.
• Keep CHANGELOG.md under [Unreleased] until an explicit version bump/release.
• Every new env variable must appear in .env.example — no exceptions.
• Docs first is fine, but docs-never is not. Even minimal docs are better than none.