update-docs

name	update-docs
description	Use when files under docs/ may be stale. Discovers commits since the last docs update, maps changed source files to affected conceptual documentation, and brings docs/*.md back into sync.

Updating the Docs

Governing spec sections: §11.1 (docs/ directory — the required conceptual docs tree), §21.5 (this skill is mandated because docs/ is a drift-prone artifact in every project).

The docs/ directory contains conceptual documentation for spotifai. Unlike the README (overview) or man pages (command reference), docs/ explains why and how in depth. It goes stale whenever a user-visible behavior, configuration key, or supported surface changes without a matching edit.

Tracking mechanism

.agent/skills/update-docs/.last-updated contains the git commit hash from the last successful run. Empty means "never run" — fall back to the repository's initial commit.

Discovery process

1. Read the baseline:

   BASELINE=$(cat .agent/skills/update-docs/.last-updated)
   

2. List commits since the baseline:

   git log --oneline "$BASELINE"..HEAD
   

3. List changed files:

   git diff --name-only "$BASELINE"..HEAD
   

4. Categorize using the mapping table below.

Mapping table

Changed files / scope	Doc(s) to update
Public API surface	docs/getting-started.md, architecture-level docs
Configuration keys / env vars	docs/configuration.md
Error messages and exit codes	docs/troubleshooting.md
Deployment / install mechanics	docs/getting-started.md

Extend this table every time you find a new source file that feeds the docs.

Update checklist

• Read baseline from .last-updated and run git log / git diff --name-only

• Read every affected docs/*.md file

• Walk the mapping table and update each doc in place

• Verify cross-links between docs still resolve

• Verify every shell example is still syntactically valid

• Run make test and the project's conformance check

• Write the new baseline:

  git rev-parse HEAD > .agent/skills/update-docs/.last-updated
  

Verification

1. Re-read every edited doc section against the current source of truth.
2. Click every internal cross-link and confirm the target still exists.
3. Confirm .last-updated was rewritten.

Skill self-improvement

1. Grow the mapping table with any new source → doc relationship you discovered.
2. Record recurring patterns you had to invent.
3. Commit the skill edit alongside the docs change so the knowledge compounds.