# R-doc-sync

> Sync project docs after a code change — stale references, affected sections.

- Skill: `roxabi/r-doc-sync` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add roxabi/r-doc-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/roxabi/r-doc-sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Roxabi (https://skillmd.com/u/roxabi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/roxabi/r-doc-sync

---


# Doc Sync

Let:
  δ := change description | K := keywords from δ (tools, config fields, CLI flags, paths, functions)
  SRC ∈ {working-tree, staged, last-commit} | D := {doc files referencing K}
  EDITED := [] — accumulator of modified files

Code change → find **every** doc referencing affected concepts → update.

**⚠ Continuous pipeline. Stop only on: Cancel or Phase 6 completion.**

```
/R-doc-sync                             → auto-detect from working tree or last commit
/R-doc-sync "gitleaks → trufflehog"     → user-supplied description
```

## Phase 1 — Parse Input

δ := `$ARGUMENTS` ∨ derive from git (first non-empty wins):

```bash
git diff --stat            # 1. unstaged
git diff --cached --stat   # 2. staged
git diff HEAD~1..HEAD --stat && git log -1 --format="%s%n%b"  # 3. last commit
```

Record SRC. ¬δ after scan → ask user describe change.

## Phase 2 — Discover Context

**2a.** `cat .dev/stack.yml 2>/dev/null` → ∃ `docs.path` → DOCS_ROOT = docs.path; else project root.

**2b.** `ls .claude-plugin/marketplace.json 2>/dev/null` → ∃ → `PLUGINS_REPO=$(pwd)`. Skip to 2d.

**2c.** Locate plugin repo:
```bash
[ -n "$ROXABI_PLUGINS_DIR" ] && echo "$ROXABI_PLUGINS_DIR"
for d in ../*/; do [ -f "${d}.claude-plugin/marketplace.json" ] && [ -d "${d}plugins" ] && echo "$d" && break; done
```
First hit → `PLUGINS_REPO`. ¬found → warn + skip plugin docs.

**2d.** Plugin name:
```bash
REPO=$(gh repo view --json name --jq '.name')
ls "$PLUGINS_REPO/plugins/"
```
Exact ∨ kebab-case match → auto-set. Multiple/¬match → ask user ¬found → warn + skip SKILL.md.

**2e.** `ls "$PLUGINS_REPO/plugins/$PLUGIN_NAME/skills/"` → one → use. Multiple → ask user

## Phase 3 — Read Changes + Extract K

```bash
git diff --name-only                  # SRC=working-tree
git diff --cached --name-only         # SRC=staged
git diff HEAD~1..HEAD --name-only     # SRC=last-commit
```

Read changed files. Extract K: tool/library names (added/removed/replaced), config fields, CLI flags, env vars, paths, functions, classes, renamed concepts.

K must include **both old and new** names for renames (grep finds stale refs).

## Phase 4 — Scan Docs for Stale References

```bash
# Project docs (exclude node_modules, .venv, vendor, dist, .git)
find . -type f \( -name "*.md" -o -name "*.mdx" \) \
  -not -path "*/node_modules/*" \
  -not -path "*/.venv/*" \
  -not -path "*/vendor/*" \
  -not -path "*/dist/*" \
  -not -path "*/.git/*"
```

∀ k ∈ K: grep across docs. D = {file | ∃ k ∈ K : k ∈ file.content}.

Always include (even if K ∉ content): `CLAUDE.md`, root `README.md`, plugin `README.md` (∃ PLUGINS_REPO), matching `SKILL.md` files.

Display:
```
Docs referencing changed concepts:
  CLAUDE.md                              2 matches (gitleaks)
  docs/guides/deployment.mdx             1 match (gitleaks)
  plugins/dev-core/hooks/README.md       3 matches (gitleaks, .gitleaks.toml)
  README.md                              0 matches (always checked)
  ...

{|D|} docs to review.
```

|D| = 0 (only always-included, 0 matches) → present choice **Force update core docs** | **Skip** → Skip: Phase 6.

## Phase 5 — Update Docs

∀ file ∈ D (order: CLAUDE.md → README.md → SKILL.md → rest alphabetically):

Targeted edits only — find affected section, update those lines. ¬rewrite unrelated. Append to EDITED after each.

| Doc type | Audience | Guidelines |
|----------|----------|------------|
| `CLAUDE.md` | LLM | Codebase instructions, paths, conventions. Precise. |
| `README.md` (root) | Humans | User perspective. ¬implementation details. |
| `SKILL.md` | LLM | Skill instructions. ¬bump version unless behavior changed. |
| Plugin `README.md` | Humans | Usage, install, triggers. |
| `docs/**/*.md{,x}` | Devs | Standards, guides. Match style. |
| ADRs (`adr/`) | Devs | ¬edit (immutable). Warn if stale. |
| `references/*.md` | LLM | Reference material. Keep factual. |
| Agent files | LLM | Update tool/config references. |

**Per file:** grep K → locate lines → read ±10 context → replace old with new. ¬match but always-included → add section only if δ introduces relevant concept.

**Stale ADR:** ∀ ADR ∈ D: ¬edit. Display: `⚠️  ADR {number} references {keyword} — consider new ADR if decision changed.`

## Phase 6 — Summary

```
Doc Sync Complete
=================

  Change:  <one-line δ>
  Source:  <SRC>
  Scanned: <N> doc files for <|K|> keywords

  Updated:
    CLAUDE.md                           ✅ <section>
    plugins/dev-core/hooks/README.md    ✅ <section>
    ...

  Skipped:
    README.md                           ⏭ no references found
    docs/architecture/adr/005-...       ⏭ ADR (immutable)
    ...

  {|EDITED|} files updated, {|D| - |EDITED|} skipped.
```

→ present choice **Commit project docs** | **Commit all (project + plugin)** | **Skip**

Commit → `git add ${EDITED}` + `docs:` prefix. Plugin repo ≠ CWD ∧ plugin files ∈ EDITED → "Commit `$PLUGINS_REPO` separately."

## Edge Cases

| Scenario | Behavior |
|----------|----------|
| ¬git repo | Read docs from CWD, skip git context |
| ¬CLAUDE.md ∨ ¬README.md | Skip, warn |
| ¬PLUGINS_REPO | Project docs only |
| ¬plugin dir | Project docs only, warn |
| δ vague | → ask user narrow to one feature |
| Unrelated files changed | Focus on δ only |
| SRC=working-tree ∧ ¬PLUGINS_REPO | Warn to set `$ROXABI_PLUGINS_DIR` |
| Rename A → B | K includes both; grep finds stale A |
| ADR references K | Warn, ¬edit |
| |D| > 20 | List, present choice: **Update all** ∨ **Select** ∨ **Skip** |

$ARGUMENTS