Initial commit

shavakan/cleanup-docs.md

@@ -0,0 +1,181 @@
+---
+description: Sync documentation with code - fix dead links, update API docs, remove outdated content
+---
+
+# Sync Documentation with Code
+
+Ensure docs accurately reflect current codebase. Remove outdated content, fix dead links, update API docs.
+
+## Prerequisites
+
+**Safety requirements:**
+1. Git repository with clean working tree
+2. Backup branch created automatically
+3. Validation after each doc update category (if tests exist)
+
+**Run prerequisite check:**
+
+```bash
+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:
+```bash
+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
+
+```markdown
+<!-- 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