Sync Documentation with Code

Ensure docs accurately reflect current codebase. Remove outdated content, fix dead links, update API docs.

Prerequisites

Safety requirements:

Git repository with clean working tree
Backup branch created automatically
Validation after each doc update category (if tests exist)

Run prerequisite check:

PLUGIN_ROOT="$HOME/.claude/plugins/marketplaces/shavakan"

if [[ ! "$PLUGIN_ROOT" =~ ^"$HOME"/.* ]]; then
  echo "ERROR: Invalid plugin root path"
  exit 1
fi

PREREQ_SCRIPT="$PLUGIN_ROOT/commands/cleanup/scripts/check-prerequisites.sh"
if [[ ! -f "$PREREQ_SCRIPT" ]]; then
  echo "ERROR: Prerequisites script not found"
  exit 1
fi

PREREQ_OUTPUT=$(mktemp)
if "$PREREQ_SCRIPT" --skip-tests > "$PREREQ_OUTPUT" 2>&1; then
  source "$PREREQ_OUTPUT"
  rm "$PREREQ_OUTPUT"
else
  cat "$PREREQ_OUTPUT"
  rm "$PREREQ_OUTPUT"
  exit 1
fi

This exports: TEST_CMD, BACKUP_BRANCH, LOG_FILE

Additional Instructions

$ARGUMENTS

Objective

Synchronize documentation with current codebase state - eliminate inaccuracies, fix broken references, ensure examples work.

Documentation Issues

Dead links - Internal links to moved/deleted files, external 404s, broken anchor references

Outdated API docs - Function signatures changed, parameters added/removed/renamed, return types mismatched, deprecated methods still documented

Stale content - Removed features still documented, old tooling instructions, architecture docs contradicting code, examples using deprecated APIs

Incorrect paths - Wrong import examples, outdated file structure diagrams, command examples referencing moved files

Missing docs - New features without documentation, API endpoints undescribed, configuration options undocumented, breaking changes not in changelog

Execution

Phase 1: Audit Documentation

Scan all docs and cross-reference with codebase. Documentation typically lives in: README.md, docs/ directory, API documentation (JSDoc/docstrings), CHANGELOG.md, CONTRIBUTING.md, inline examples.

For each issue found, capture location, problem description, and suggested fix. Present findings grouped by category with counts and severity.

Gate: User must review full audit before proceeding.

Phase 2: Prioritize Fixes

Present audit findings with impact assessment:

Fix documentation issues?

□ Critical - Dead links + wrong API signatures + missing docs
□ High - Stale setup + removed features + incorrect paths
□ Medium - Outdated diagrams + deprecated tool references
□ Custom - Select specific categories
□ Cancel

Gate: Get user approval on which categories to fix.

Phase 3: Fix Issues

For each approved category:

Dead links: Update to new location if file moved, remove if deleted, find replacement for broken external URLs, fix anchor links to match current headings

Outdated API docs: Compare documented signatures with actual code, update parameters/return types to match reality, add version notes ("Changed in v2.0.0"), note breaking changes in CHANGELOG

Stale content: Remove sections about deleted features, update setup instructions for current tools, note what replaced old features, update architecture diagrams, test and fix code examples

Incorrect paths: Find current file locations, update import examples, fix command line examples, correct file tree diagrams

Missing docs: Document new public APIs, add configuration option descriptions, note breaking changes in CHANGELOG, write migration guides for major changes

Critical: Test all code examples actually work. Verify links resolve correctly. One category at a time with test validation between each.

Gate: Tests must pass before moving to next category.

Phase 4: Report Results

Summarize: dead links fixed, API docs synchronized, stale content removed/updated, paths corrected, missing docs added, documentation accuracy improvement.

Delete the backup branch after successful completion:

git branch -D "$BACKUP_BRANCH"

Documentation Priority Tiers

Essential (always accurate): README.md, API documentation, CHANGELOG.md, migration guides, setup/installation

Important (reasonably current): Architecture docs, contributing guide, examples, troubleshooting

Nice-to-have (update as needed): Tutorials, design decisions, performance notes, comparisons

Example API Doc Correction

<!-- Before (outdated) -->
## authenticate(username, password)
Authenticates a user with username and password.

<!-- After (corrected) -->
## authenticate(credentials)
Authenticates a user with credentials object.

**Parameters:**
- `credentials.email` (string) - User email
- `credentials.password` (string) - User password

**Changed in v2.0.0:** Previously accepted separate username and password parameters.

Safety Constraints

CRITICAL:

Verify content is truly outdated before removing - check git history
Test all code examples actually compile and run
Keep migration context - when removing features, note what replaced them
Update CHANGELOG when fixing API documentation errors
One category at a time with test validation
Commit granularly - separate commits for dead links, API updates, etc.
Check markdown renders correctly after edits

If examples fail: Don't update docs to match broken code. Fix the code or mark the feature as broken in docs with an issue reference.

After Cleanup

Review with code-reviewer agent before pushing:

Use shavakan-agents:code-reviewer to verify changes don't introduce issues.

Related Commands

/shavakan-commands:cleanup - Full repository audit
/shavakan-commands:cleanup-dead-code - Remove unused code

/cleanup-docs