update-project-docs

name	update-project-docs
description	Intelligently refreshes project documentation by analyzing repository structure, modified files, git changes, configuration updates, and new features. Ensures README, CONTRIBUTING, CHANGELOG, and docs/* remain synchronized with the actual implementation.
argument-hint	Provide a description of the documentation update or run after code changes to synchronize documentation with the repository.
user-invocable	true

Intelligent Project Documentation Synchronizer

Purpose

This skill ensures project documentation remains synchronized with the actual repository implementation.

It analyzes:

• repository structure
• modified files and directories
• configuration updates
• environment variables
• dependencies
• new modules or features
• deleted functionality

Documentation is updated only where changes affect documentation.

---

When To Use This Skill

Use this skill when:

• new features were implemented
• files or modules were added
• directories were restructured
• APIs were modified
• scripts or commands changed
• environment variables were added or removed
• dependencies were updated
• deployment setup changed
• documentation drift is suspected

Typical triggers:

after feature development
before opening a pull request
after infrastructure changes
after refactoring modules

---

Documentation Targets

Primary documents:

README.md CONTRIBUTING.md CHANGELOG.md

Secondary documentation:

• docs/
• docs/README.md
• docs/setup/
• docs/deployment/
• docs/architecture/
• docs/api/
• docs/features/

Configuration files that affect docs:

• package.json
• package-lock.json
• .env.example
• example.env.local
• tsconfig.json
• next.config.ts
• Dockerfile
• docker-compose.yml
• Makefile

Source directories that define behavior:

• src/
• app/
• pages/
• routes/
• features/
• modules/
• services/
• lib/
• api/
• scripts/

---

Source-of-Truth Priority

Always treat the following as authoritative:

1️⃣ Source code 2️⃣ Configuration files 3️⃣ Environment variable definitions 4️⃣ Infrastructure configuration 5️⃣ Existing documentation

If documentation conflicts with code, update documentation.

Never invent undocumented functionality.

---

Workflow

---

Step 1 — Detect Modified Files and Directories

Identify changes introduced in the repository.

Run:

git diff --name-only HEAD

or for PR context:

git diff --name-only origin/main

Also inspect staged changes:

git diff --name-only --staged

Determine:

• modified files
• newly added files
• removed files
• renamed directories

Group changes by directory/module.

Example classification:

src/features/wishlist/*
src/api/products/*
src/components/*
config/*
scripts/*

---

Step 2 — Detect Documentation Impact

Map changed files to documentation areas.

Examples:

Changed Path	Documentation Impact
src/api	API docs
src/features	Feature documentation
src/components	UI documentation
package.json	scripts + setup
Dockerfile	deployment docs
.env.example	environment configuration
scripts	developer workflow
routes	API / routing docs

Mark documentation sections that require updates.

---

Step 3 — Detect New Modules or Features

Identify newly added directories.

Example:

src/features/collaborator-wishlist

If a new feature/module exists:

Update:

README feature list
docs/features/*
architecture docs

Generate documentation for new modules when missing.

---

Step 4 — Detect Removed Functionality

If files or modules were removed:

Remove or update documentation referencing them.

Example:

removed src/api/legacy-orders

Update:

docs/api
README

---

Step 5 — Detect Configuration Changes

Inspect configuration changes.

Important sources:

package.json
.env.example
Dockerfile
docker-compose.yml
Makefile
next.config.ts

Check for:

• new scripts
• removed scripts
• dependency updates
• runtime version changes
• environment variables added or removed

Update documentation sections accordingly.

---

Step 6 — Detect Environment Variable Changes

Parse:

.env.example
example.env.local

Compare with documentation.

Update:

README environment section
docs/setup
docs/configuration

Document:

• variable name
• purpose
• example value

---

Step 7 — Detect Dependency Changes

Inspect dependency updates in:

package.json
requirements.txt
go.mod
Cargo.toml

Update documentation for:

• required runtime versions
• dependency installation instructions
• new tooling requirements

---

Step 8 — Detect Script Changes

Inspect package.json scripts.

Example:

"scripts": {
  "dev": "next dev",
  "build": "next build",
  "lint": "eslint ."
}

Update:

README scripts section
docs/development

Ensure commands remain accurate.

---

Step 9 — Update Documentation Sections

Apply targeted updates.

Affected sections include:

README

Update:

• project overview
• feature list
• setup instructions
• scripts
• environment variables
• architecture summary

---

CHANGELOG

Generate entries based on git changes.

Example:

## Added
- collaborator wishlist feature

## Fixed
- filter infinite loading issue

## Refactored
- API request logic

---

Architecture Documentation

Update when directories change.

Reflect:

src/features
src/modules
src/services

Explain module responsibilities.

---

API Documentation

If API routes changed:

Update:

docs/api/*

Include:

• endpoint description
• parameters
• response format

---

Deployment Documentation

Update when:

Dockerfile
docker-compose.yml

changes.

Document:

• build commands
• runtime environment
• container setup

---

Step 10 — Cross-Document Consistency Check

Ensure no contradictions between:

README.md
CONTRIBUTING.md
CHANGELOG.md
docs/*

Validate:

• setup instructions match scripts
• environment variables match .env.example
• deployment docs match Docker configuration

---

Step 11 — Navigation and Links

Verify documentation navigation.

Ensure:

README links to docs docs index links to subdocs no broken relative links

Prevent orphan documentation.

---

Step 12 — Markdown Quality Check

Validate formatting.

Ensure:

• correct heading hierarchy
• valid code blocks
• consistent formatting
• no malformed markdown

---

Decision Rules

If documentation already matches code

Do not rewrite the document.

Only report:

Documentation is already synchronized.

---

If documentation gaps exist

Generate missing sections using verified repository facts only.

---

If behavior cannot be confirmed

Write explicitly:

This behavior is not explicitly defined in the repository.

Never guess.

---

Output Format

Return a structured report.

---

Documentation Update Summary

Modified documentation:

• README.md
• docs/api/products.md
• docs/setup/environment.md

---

Documentation Changes

Updated

• documented new environment variables
• updated setup instructions
• refreshed API documentation

Added

• docs/features/collaborator-wishlist.md

Removed

• outdated API documentation for legacy endpoints

---

CHANGELOG Entry

Provide suggested changelog entry.

Example:

## Added
- collaborator wishlist feature

## Updated
- environment variable documentation

## Fixed
- outdated setup instructions

---

Open Questions

List items that could not be verified from repository.

Example:

Environment variable PAYMENT_SECRET usage not found in code.

---

Example Commands

Refresh docs after repository changes:

/update-project-docs refresh documentation after feature development

Update API documentation:

/update-project-docs update API docs after route changes

Update environment documentation:

/update-project-docs sync environment variables

Update deployment documentation:

/update-project-docs update Docker and deployment setup docs

---

# What This Upgrade Adds

| Improvement | Benefit |
|---|---|
Git change awareness | updates docs only when necessary |
Directory analysis | detects new modules automatically |
Feature detection | updates README features |
Changelog generation | automatic release documentation |
API change detection | keeps API docs accurate |
Env variable tracking | prevents missing configuration docs |
Dependency tracking | keeps setup instructions correct |
Cross-doc validation | prevents conflicting instructions |