Documentation sync

<!-- TÜRKÇE AÇIKLAMA ─────────────── Bu skill, kodda yapılan önemli değişikliklerden sonra hangi dokümantasyon dosyalarının eskidiğini tespit edip günceller. README, API docs, .env.example, CHANGELOG ve mimari diyagramlar incelenerek eski bilgiler düzeltilir. "Docs ile kod arasındaki uçurum" problemini kapatır. NE ZAMAN: API eklendiğinde/değiştiğinde, yeni env variable eklendiğinde, büyük refactor sonrası, merge öncesi veya sonrası. ÇIKTI: Güncellenmiş doc dosyaları + değişim özet raporu. -->

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.