Updates documentation after code changes with quality gates, slop detection, and accuracy checks. Use when code changes require corresponding doc updates.
Instrucciones de origen · Vista previa de solo lectura
name
doc-updates
description
Updates documentation after code changes with quality gates, slop detection, and accuracy checks. Use when code changes require corresponding doc updates.
Use this skill when code changes require updates to the README, plans, wikis, or docstrings. Run Skill(sanctum:git-workspace-review) first to capture the change context.
System Capabilities
The documentation update workflow includes several specialized functions. It identifies redundancy through consolidation detection and enforces directory-specific style rules, with strict limits for docs/ and more lenient ones for the book/ directory. The system also verifies the accuracy of version numbers and component counts and integrates with the LSP for semantic documentation verification in supported versions of Claude Code.
When NOT To Use
README-specific updates - use update-readme instead
Complex multi-file consolidation - use doc-consolidation
doc-updates:slop-scanned - AI marker detection via scribe
doc-updates:plugins-synced - plugin.json ↔ disk audit
- plugin.json ↔ documentation sync
doc-updates:capabilities-synced
doc-updates:accuracy-verified
doc-updates:preview
Step 1: Collect Context (context-collected)
Validate Skill(sanctum:git-workspace-review) has been run.
Use its notes to understand the delta.
Identify the features or bug fixes that need documentation updates.
CHANGELOG Reference (critical for version sync):
# Check recent CHANGELOG entries for undocumented featureshead -100 CHANGELOG.md
# Compare documented version vs plugin versions
grep -E "^\[.*\]" CHANGELOG.md | head -3
for p in plugins/*/.claude-plugin/plugin.json; do
jq -r '"\(.name): \(.version)"'"$p"done | head -5
Cross-reference CHANGELOG entries against:
book/src/reference/capabilities-reference.md - All skills/commands/agents
Plugin documentation in book/src/plugins/ - Per-plugin docs
Plugin READMEs - Quick reference docs
Step 2: Identify Targets (targets-identified)
List the relevant files from the scope across all documentation locations:
docs/ - Reference documentation (strict style)
book/ - Technical book content (lenient style)
README.md files at project and plugin roots
wiki/ entries if present
Docstrings in code files
Prioritize user-facing documentation first, then supporting plans and specifications.
When architectural work is planned, confirm whether an Architecture Decision Record (ADR) already exists in wiki/architecture/ (or wherever ADRs are located).
Add missing ADRs to the target list before any implementation begins.
Step 2.5: Check for Consolidation (consolidation-checked)
Load: @modules/consolidation-integration.md
Purpose: Detect redundancy and bloat before making edits.
Bloated committed docs (files exceeding 500 lines in docs/, 1000 in book/)
Stale files (outdated content that should be deleted)
User approval required before:
Merging content from one file to another
Deleting stale or redundant files
Splitting bloated files
Skip options:
Use --skip-consolidation flag to bypass this phase
Select specific items instead of processing all
Exit criteria: User has approved/skipped all consolidation opportunities.
Step 3: Apply Edits (edits-applied)
Update each file with grounded language: explain what changed and why.
Reference specific commands, filenames, or configuration options where possible.
For docstrings, use the imperative mood and keep them concise.
For ADRs, see modules/adr-patterns.md for complete template structure, status flow, immutability rules, and best practices.
Step 4: Enforce Guidelines (guidelines-verified)
Load: @modules/directory-style-rules.md
Style Enforcement
Maintain consistent documentation by applying directory-specific rules. The system checks for and removes filler phrases such as "in order to" or "it should be noted" and ensures that no emojis are present in the body text of technical documents. Use grounded language with specific references rather than vague claims, and maintain an imperative mood for instructions. For lists of three or more items, prefer bullets over prose to improve scannability.
The audit will issue warnings for paragraphs that exceed length limits or files that surpass the established line count thresholds. We also flag marketing language and abstract adjectives like "capable" or "smooth" to maintain a technical and direct tone across all project documentation.
Step 4.25: AI Slop Detection (slop-scanned)
Run Skill(scribe:slop-detector) on edited documentation to detect AI-generated content markers.
Scribe Integration
The scribe plugin provides thorough AI slop detection:
Tier 1 words: delve, tapestry, comprehensive, leveraging, etc.
Phrase patterns: "In today's fast-paced world", "cannot be overstated"
Structural markers: Excessive em dashes, bullet overuse, sentence uniformity
Sycophantic phrases: "I'd be happy to", "Great question!"
Writing Style Guidelines
For enhanced writing quality, check for elements-of-style:writing-clearly-and-concisely:
# If superpowers/elements-of-style is installed:
Skill(elements-of-style:writing-clearly-and-concisely)
# Fallback if not installed - use scribe:doc-generator principles:
Skill(scribe:doc-generator) --remediate
The fallback provides equivalent guidance:
Ground every claim with specifics
Trim rhetorical crutches (no formulaic openers/closers)
Use numbers, commands, filenames over adjectives
Balance bullets with narrative prose
Show authorial perspective (trade-offs, reasoning)
Remediation
If slop score exceeds 2.5 (moderate), run:
Agent(scribe:doc-editor) --target [file]
This provides interactive section-by-section cleanup with user approval.
