From rkstack
Post-ship documentation update workflow. Audits all .md files against code changes, auto-updates factual content, gates risky changes, polishes CHANGELOG voice, and ensures cross-doc consistency. Run after shipping or when documentation may be stale.
npx claudepluginhub mrkhachaturov/ccode-personal-plugins --plugin rkstackThis skill is limited to using the following tools:
<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Guides TDD-style skill creation: pressure scenarios as tests, baseline agent failures, write docs to enforce compliance, verify with RED-GREEN-REFACTOR.
# === RKstack Preamble (document-release) ===
# Read detection cache (written by session-start via rkstack detect)
if [ -f .rkstack/settings.json ]; then
cat .rkstack/settings.json
else
echo "WARNING: .rkstack/settings.json not found — detection cache missing"
fi
# Session-volatile checks (can change mid-session)
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
_HAS_CLAUDE_MD=$([ -f CLAUDE.md ] && echo "yes" || echo "no")
echo "BRANCH: $_BRANCH"
echo "CLAUDE_MD: $_HAS_CLAUDE_MD"
Use the detection cache and preamble output to adapt your behavior:
detection.flowType (web or default). If web: check React/Vue/Svelte patterns, responsive design, component architecture. If default: CLI tools, MCP servers, backend scripts.just commands instead of raw shell.detection.stack for what's in the project and detection.stats for scale (files, code, complexity).detection.repoMode for solo vs collaborative.detection.services for Supabase and other service integrations.ALWAYS follow this structure for every AskUserQuestion call:
_BRANCH value from preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)RECOMMENDATION: Choose [X] because [one-line reason] — always prefer the complete option over shortcuts (see Completeness Principle). Include Completeness: X/10 for each option. Calibration: 10 = complete implementation (all edge cases, full coverage), 7 = covers happy path but skips some edges, 3 = shortcut that defers significant work.A) ... B) ... C) ... — when an option involves effort, show both scales: (human: ~X / CC: ~Y)Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with AI. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans.
Effort reference — always show both scales:
| Task type | Human team | CC + AI | Compression |
|---|---|---|---|
| Boilerplate | 2 days | 15 min | ~100x |
| Tests | 1 day | 15 min | ~50x |
| Feature | 1 week | 30 min | ~30x |
| Bug fix | 4 hours | 15 min | ~20x |
Include Completeness: X/10 for each option (10=all edge cases, 7=happy path, 3=shortcut).
When completing a skill workflow, report status using one of:
It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result."
Bad work is worse than no work. You will not be penalized for escalating.
Escalation format:
STATUS: BLOCKED | NEEDS_CONTEXT
REASON: [1-2 sentences]
ATTEMPTED: [what you tried]
RECOMMENDATION: [what the user should do next]
# Detect base branch — try platform tools first, fall back to git
_BASE=""
# GitHub
if command -v gh &>/dev/null && gh auth status &>/dev/null 2>&1; then
_BASE=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || true)
fi
# GitLab
if [ -z "$_BASE" ] && command -v glab &>/dev/null; then
_BASE=$(glab mr view --output json 2>/dev/null | grep -o '"target_branch":"[^"]*"' | cut -d'"' -f4 || true)
fi
# Plain git fallback
if [ -z "$_BASE" ]; then
for _CANDIDATE in main master develop; do
if git show-ref --verify --quiet "refs/heads/$_CANDIDATE" 2>/dev/null || \
git show-ref --verify --quiet "refs/remotes/origin/$_CANDIDATE" 2>/dev/null; then
_BASE="$_CANDIDATE"
break
fi
done
fi
_BASE=${_BASE:-main}
echo "BASE_BRANCH: $_BASE"
Use _BASE (the value printed above) as the base branch for all diff operations. In prose and code blocks, reference it as <base> — the agent will substitute the detected value.
You are running the /document-release workflow. This runs after code is committed (PR
exists or about to exist) but before the PR merges. Your job: ensure every documentation file
in the project is accurate, up to date, and written in a friendly, user-forward voice.
You are mostly automated. Make obvious factual updates directly. Stop and ask only for risky or subjective decisions.
Announce at start: "I'm using the document-release skill to audit and update documentation."
Only stop for:
Never stop for:
NEVER do:
Write tool on CHANGELOG.md -- always use Edit with exact old_string matchesCheck the current branch. If on the base branch, abort: "You're on the base branch. Run from a feature branch."
Gather context about what changed:
git diff <base>...HEAD --stat
git log <base>..HEAD --oneline
git diff <base>...HEAD --name-only
find . -maxdepth 2 -name "*.md" -not -path "./.git/*" -not -path "./node_modules/*" -not -path "./.upstreams/*" | sort
Classify the changes into categories relevant to documentation:
Output a brief summary: "Analyzing N files changed across M commits. Found K documentation files to review."
Read each documentation file and cross-reference it against the diff. Use these generic heuristics (adapt to whatever project you're in -- these are not project-specific):
README.md:
CLAUDE.md / project instructions:
CONTRIBUTING.md -- New contributor smoke test:
ARCHITECTURE.md:
Any other .md files:
For each file, classify needed updates as:
Make all clear, factual updates directly using the Edit tool.
For each file modified, output a one-line summary describing what specifically changed -- not just "Updated README.md" but "README.md: added /new-skill to skills table, updated skill count from 9 to 10."
Never auto-update:
For each risky or questionable update identified in Step 2, use AskUserQuestion with:
RECOMMENDATION: Choose [X] because [one-line reason]Apply approved changes immediately after each answer.
CRITICAL -- NEVER CLOBBER CHANGELOG ENTRIES.
This step polishes voice. It does NOT rewrite, replace, or regenerate CHANGELOG content.
Rules:
old_string matches -- never use Write to overwrite CHANGELOG.md.If CHANGELOG was not modified in this branch: skip this step.
If CHANGELOG was modified in this branch, review the entry for voice:
After auditing each file individually, do a cross-doc consistency pass:
If TODOS.md does not exist, skip this step.
Completed items not yet marked: Cross-reference the diff against open TODO items. If a
TODO is clearly completed by the changes in this branch, move it to the Completed section
with **Completed:** vX.Y.Z (YYYY-MM-DD). Be conservative -- only mark items with clear
evidence in the diff.
Items needing description updates: If a TODO references files or components that were significantly changed, its description may be stale. Use AskUserQuestion to confirm whether the TODO should be updated, completed, or left as-is.
New deferred work: Check the diff for TODO, FIXME, HACK, and XXX comments. For
each one that represents meaningful deferred work (not a trivial inline note), use
AskUserQuestion to ask whether it should be captured in TODOS.md.
Empty check first: Run git status (never use -uall). If no documentation files were
modified by any previous step, output "All documentation is up to date." and exit without
committing.
Commit:
git add -A or git add .).git commit -m "$(cat <<'EOF'
docs: update project documentation
Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
Structured doc health summary (final output):
Output a scannable summary showing every documentation file's status:
Documentation health:
README.md [status] ([details])
CLAUDE.md [status] ([details])
CONTRIBUTING.md [status] ([details])
CHANGELOG.md [status] ([details])
TODOS.md [status] ([details])
Where status is one of: