s-docs

name	s-docs
description	Update project documentation - detects stale docs and updates README, ARCHITECTURE, CHANGELOG, CLAUDE.md

/s:docs - Documentation Update

Scan project documentation for staleness, detect gaps, propose updates, and apply them after user approval. Keeps docs in sync with the actual codebase.

When to Use

• After shipping a feature or completing a phase
• Before a release
• When onboarding new contributors
• When you suspect docs are out of date
• As part of /s:retro follow-up

Instructions

Step 1: Scan for Documentation Files

Search the project root and common locations for documentation files:

1. Root-level docs: README.md, ARCHITECTURE.md, CONTRIBUTING.md, CLAUDE.md, CHANGELOG.md, LICENSE
2. API docs: docs/api/, openapi.yaml, swagger.json, any *.api.md files
3. Guides: docs/guides/, docs/getting-started.md, SETUP.md, INSTALL.md
4. Project memory: .planning/PROJECT.md, .planning/REQUIREMENTS.md, .planning/ROADMAP.md
5. Package metadata: package.json (description, scripts), pyproject.toml, Cargo.toml

Build an inventory of all documentation files found.

Step 2: Check Each Document for Staleness

For each documentation file found, perform these checks:

README.md

• Does the project description match the current state?
• Do install/setup instructions work with the current dependency versions?
• Are referenced scripts (e.g., npm run dev) still valid in package.json?
• Are listed features/skills/commands still accurate?
• Do any file paths referenced in the README still exist?

ARCHITECTURE.md

• Do referenced directories and files exist?
• Does the described module structure match the actual directory layout?
• Are data flow descriptions consistent with current imports/exports?
• Are technology choices listed still accurate (check package.json, etc.)?

CONTRIBUTING.md

• Are branch naming conventions consistent with current practice?
• Do PR templates/checklists match the current workflow?
• Are testing instructions current?

CLAUDE.md

• Do referenced skill names match actual skill directories?
• Are workflow rules consistent with current skill implementations?
• Do referenced agent files exist?
• Are MCP references current?

CHANGELOG.md

• Is the latest version entry present?
• Does it reflect the most recent changes (compare with git log)?
• Are entries formatted consistently?

API Documentation

• Do documented endpoints match actual route definitions?
• Are request/response schemas accurate?
• Are authentication requirements documented correctly?
• Do example requests work?

Step 3: Generate Staleness Report

Present findings to the user in this format:

## Documentation Status Report

### Current (no changes needed)
- LICENSE - up to date
- CONTRIBUTING.md - up to date

### Stale (updates recommended)
- README.md
  - Line 15: References `npm run start` but script is now `npm run dev`
  - Line 42: Lists 12 skills but there are now 27
  - Missing: No mention of browser skills added in Phase 4

- ARCHITECTURE.md
  - Line 8: References `src/utils/` which was renamed to `src/lib/`
  - Diagram does not include the new `agents/` directory

### Missing (recommended to create)
- ARCHITECTURE.md - project has grown complex enough to benefit from this
- API documentation - 5 API endpoints found with no docs

Step 4: Propose Specific Updates

For each stale document, show the proposed changes:

1. Show the current text that needs updating
2. Show the proposed replacement text
3. Explain why the change is needed

Format proposals as diffs or before/after blocks so the user can review them clearly.

Step 5: Apply Updates After Approval

1. Ask the user: "Apply all updates, or review them one by one?"
2. Based on user preference:
   • Apply all: Make all proposed changes
   • One by one: Show each change and ask for approval before applying
3. For each applied change, use the Edit tool to make precise modifications
4. Do NOT rewrite entire files unless the majority of content has changed

Step 6: Handle Missing Documentation

If important documentation files are missing, suggest creating them based on project type:

Project Type	Suggested Docs
Any	README.md, CHANGELOG.md
Library/Package	API reference, CONTRIBUTING.md
Web Application	ARCHITECTURE.md, deployment guide
CLI Tool	Usage guide, man page
Plugin	Installation guide, skill reference

For each suggestion, offer to generate a first draft based on the current codebase.

Step 7: Update State

1. Update .planning/STATE.md:
   • Add a decision entry: | {DATE} | Docs updated | {list of files updated} |
2. Note any documentation gaps that remain

Step 8: Summary Output

Present the final status:

Documentation update complete.

Updated:
- README.md (3 changes applied)
- CHANGELOG.md (1 version entry added)

Still current:
- CONTRIBUTING.md
- LICENSE

Gaps remaining:
- ARCHITECTURE.md does not exist (recommended for this project size)
- No API documentation for /api/v2/ endpoints

All project documentation is now in sync with the codebase.

Or, if everything was already current:

Documentation is up to date. No changes needed.

All {N} documentation files are consistent with the current codebase.

Rules

1. Never silently overwrite documentation - always show changes and get approval
2. Preserve the original author's voice and style when making updates
3. Do not add filler content or expand documents unnecessarily
4. Focus on accuracy over completeness - a short correct doc beats a long wrong one
5. When updating CHANGELOG.md, follow the existing format (do not impose a new format)
6. Keep CLAUDE.md updates minimal and precise - it is loaded every session

Integration

• /s:ship can trigger this skill as part of the shipping process
• /s:retro may identify documentation gaps as action items
• /s:verify checks that documentation claims match reality
• Session-start hook reads CLAUDE.md, so keeping it accurate is critical