Doc Updates

Documentation Update Workflow

When To Use

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

Required TodoWrite Items

1. doc-updates:context-collected - Git context + CHANGELOG review
2. doc-updates:targets-identified
3. doc-updates:consolidation-checked (skippable)
4. doc-updates:edits-applied
5. doc-updates:guidelines-verified
6. doc-updates:slop-scanned - AI marker detection via scribe
7. doc-updates:plugins-synced - plugin.json ↔ disk audit
8. doc-updates:capabilities-synced - plugin.json ↔ documentation sync
9. doc-updates:accuracy-verified
10. 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 features
head -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.

Scan for:

• Untracked reports (ALL_CAPS *_REPORT.md, *_ANALYSIS.md files)
• 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:

Skill(scribe:slop-detector) --target [edited-files]

This detects:

• 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!"
• Punctuation stand-ins: spaced --, + for "and", semicolon splices
• Contrastive negation: "It's not X, it's Y", "X, not Y", ", not just Y"
• Consequence tails: ", so the ..." after fact after fact, with a density reading above 2.0 per 1000 words
• Over-explained fixes and negative framing: "in order to", "this ensures that", "not uncommon", and a negation-density reading per file

One command locates every finding with a file and a line, the opt-in and low-confidence categories included:

uv run --with pyyaml python scripts/slop_score.py --audit <edited-files>

Edited .py files belong in that list. The scorer reads a Python path as its comments and docstrings, keeping the line numbers, so a finding names the line to open. Notation is not prose: an arrow in a mapping table, a plus in a formula, and a character quoted because the code matches it are all code that happens to sit in a docstring.

Audience Fit

Before rewriting a document, name its reader. Every doc under maintenance already has one, stated or assumed, and an edit that ignores it drifts the doc toward serving nobody.

Skill(scribe:slop-detector)   # module: audience-targeting.md

• Read the tier off the document if it declares one. If it does not, infer the tier from where the doc sits (README and getting-started are newcomer; plugin guides are practitioner; ADRs and deep dives are expert), then state the inference in the change summary so a reviewer can correct it. When the placement gives no answer, ask, do not guess.
• Apply the cut test per section: keep what the reader needs before they can act, link what they need later, extract what only a higher tier wants, delete what no tier wants.
• Extract rather than delete. Off-tier material moves to modules/<topic>.md for a skill or docs/deep-dive/<topic>.md for a repo doc, linked from the parent's lead with one line naming who it is for.
• An update that adds expert detail to a newcomer document is the common drift. It is how a getting-started page becomes a reference manual one honest paragraph at a time.

Skip this for creative output. audience-targeting.md scopes the scribe:voice-* and session-to-post surfaces out by name.