Doc Refresh

Philosophy

Generation is solved — PitchDocs handles that. Maintenance is the unsolved problem. After the initial docs suite is created, every release needs a coordinated update: CHANGELOG entries enhanced with benefit language, README features refreshed, user guides amended, AI context files synced, and llms.txt kept current.

/doc-refresh closes the maintenance loop. It works alongside release-please: release-please handles version strings and CHANGELOG scaffolding, /doc-refresh handles prose, features, context, and metrics.

Change Detection Workflow

Step 1: Identify the Boundary

# Latest tag (the "since" point for change detection)
git describe --tags --abbrev=0 2>/dev/null

# If no tags exist, fall back to initial commit
git rev-list --max-parents=0 HEAD

# All commits since boundary
git log $(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)..HEAD --oneline --no-merges

# If a version argument was provided (e.g., v1.5.0..v1.7.0)
git log v1.5.0..v1.7.0 --oneline --no-merges

If no tags exist at all, recommend running /readme and /docs-audit fix instead — a full generation is more appropriate than a refresh for a brand-new repo.

Step 2: Parse Conventional Commits

Classify each commit into categories that map to documentation impacts:

If the repo does not use conventional commits, fall back to git diff --stat analysis — classify changes by which files they touch (source, tests, config, docs) rather than commit message prefix.

Step 3: Detect File-Level Changes

# Which areas of the project changed?
git diff --name-only $(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)..HEAD | head -50

# Specifically check for structural changes (new commands, skills, agents, config)
git diff --name-only $(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)..HEAD | grep -E '(commands/|skills/|agents/|rules/|\.config|package\.json|pyproject\.toml)'

Step 4: Build the Refresh Plan

Map detected changes to specific doc files. Output a structured plan before executing:

📋 Documentation Refresh Plan: [project-name]

Boundary: v1.6.0..HEAD (15 commits: 8 feat, 4 fix, 2 docs, 1 chore)

Docs to update:
  → CHANGELOG.md — 8 feat + 4 fix entries to enhance with benefit language
  → README.md — 2 new features detected, metrics need updating
  → docs/guides/getting-started.md — new command added, guide needs amendment
  → AGENTS.md — commands table out of date
  → llms.txt — 2 new files to add
  ⊘ .cursorrules — no drift detected
  ⊘ Package registry — no metadata changes

In plan mode, stop here and report. Otherwise, proceed to execution.

Refresh Actions Table

Orchestration Workflow

Execute in this order. Each step loads the relevant skill on demand.

Step 1: Analyse (always runs first)

Run the change detection workflow above. Produce the refresh plan. In plan mode, report and stop.

Step 2: CHANGELOG

Load the changelog skill. If release-please has already created CHANGELOG entries for this version, enhance them with benefit language rather than duplicating. If no release-please entries exist, generate from scratch using conventional commits.

Detection: check if a version header (e.g., ## [1.7.0]) or ## [Unreleased] section already exists in CHANGELOG.md with entries for the commits in scope.

Step 3: README

Load the feature-benefits skill. Run a features audit to compare current README features against the codebase. Update:

• Features section (add new, mark deprecated)
• "By the Numbers" metrics table (command counts, skill counts, etc.)
• Badge version references (note: release-please handles the version badge via x-release-please-version — do not duplicate)

Step 4: User Guides

Load the user-guides skill. Identify which guides are affected by checking if changed files relate to documented workflows. Update affected sections. Add new guides if a major new feature warrants one. Update the docs hub page if guides were added.

Step 5: AI Context Files (ContextDocs)

If ContextDocs is installed ([ -d ".claude/skills/ai-context" ]), delegate to it:

# Check if ContextDocs is available
if [ -d ".claude/skills/ai-context" ]; then
  echo "ContextDocs detected — run /contextdocs:ai-context audit to check for drift"
fi

If ContextDocs is not installed, print an advisory:

ℹ AI context file refresh skipped — install ContextDocs for AI context management:
  /plugin install contextdocs@lba-plugins

Step 6: llms.txt

Load the llms-txt skill. Regenerate if files were added, removed, or renamed since the boundary. If no structural changes, skip.

Step 7: Package Registry

Load the package-registry skill. Verify that package.json/pyproject.toml metadata (description, keywords, repository, homepage) is still current. Flag any drift.

Step 7.5: Plugin Manifest (if applicable)

If the project has a .claude-plugin/plugin.json, verify the description and keywords fields still match the current README one-liner and features. CLAUDE.md notes "update on every release" — flag stale descriptions that no longer reflect the project's scope.

Step 8: Verify (always runs last)

Load the docs-verify skill. Run full verification: broken links, stale content, llms.txt sync, heading hierarchy, badge URLs, feature coverage, quality score. Report the score and any issues found.

Step 9: Release Notes (optional)

If release-notes argument was provided or running in full mode, generate a GitHub release body from the CHANGELOG entry for this version. Format with benefit-driven language and include migration notes for breaking changes.

Release Automation Integration

The table below shows the split of responsibilities between your release automation tool and /doc-refresh. release-please (GitHub Actions) is the default; for GitLab use semantic-release with GitLab CI or release-it; for Bitbucket use semantic-release with Bitbucket Pipelines. Load the platform-profiles skill for CI/CD equivalents.

Timing: Run /doc-refresh before merging the release PR:

1. Your release tool creates a PR with version bumps and CHANGELOG skeleton
2. Run /doc-refresh to enhance CHANGELOG, update README, guides, context files
3. Commit the refreshed docs to the release branch
4. Merge the PR — the release tool creates the platform release

Anti-Patterns

• Do not run /doc-refresh and /readme in the same session — /doc-refresh updates README surgically (affected sections only), while /readme regenerates from scratch. Choose one.
• Do not duplicate CHANGELOG entries — if release-please already generated entries, enhance them with benefit language rather than creating parallel entries.
• Do not update user guides for internal refactors — only update guides when user-facing behaviour changes.
• Do not regenerate all AI context files — audit first, update only the files with actual drift.
• Do not manually update the version badge — release-please owns the x-release-please-version marker.