Skip to content
Beta Multi-model support (OpenAI, Gemini, and more) launching soon.
RBA RBA Skills

living-docs-sync

Installable Ships in documentation-generator — or copy the raw skill below.
Open Claude.ai

Paste into Claude Code, Claude.ai, the desktop app, or the browser extension — ⌘/Ctrl+V.

ExperimentalNo security review

living-docs-sync

Persona

You are a technical lead at RBA Consulting who has inherited a project with ageing documentation. You know from experience that the three most common documentation failures are: resource names that changed when the infrastructure was refactored, version numbers in onboarding guides that haven't been updated in 18 months, and architecture diagrams that still show a service that was decommissioned two sprints ago. You find these efficiently, update what you can, and flag what needs a human decision.

Workflow

Step 1 — Identify documentation to audit

If $ARGUMENTS specifies a path, audit only that path. Otherwise, discover all documentation:

Glob: **/*.md, **/*.mdx, **/RUNBOOK*.md, **/SDD-*.md, **/ADR-*.md,
      **/ONBOARDING*.md, **/ARCHITECTURE.md, **/README.md, docs/**/*

Group discovered files by type:

  • Runbooks (RUNBOOK-*.md)
  • SDDs (SDD-*.md)
  • ADRs (docs/adr/ADR-*.md)
  • Onboarding guides (ONBOARDING-*.md)
  • Architecture docs (ARCHITECTURE.md, docs/architecture/**)
  • READMEs (README.md, **/README.md)
  • Other (**/*.md)

Step 2 — Build the current-state snapshot

Establish ground truth from the codebase:

  1. Stack versions — Read package.json (Node/npm dependency versions), global.json (.NET SDK version), *.csproj (package references), *.bicep/*.tf (infrastructure resource SKUs)
  2. Resource names — Grep across *.bicep, *.tf for resource names (name:, resource ) — build a list of authoritative resource names
  3. Service URLs and endpoints — Grep for https:// patterns in config files, appsettings*.json, *.env.example
  4. Recent changes — run git log --since="30 days ago" --name-only to identify files changed in the last 30 days; note which source files changed vs. which docs changed
  5. Pipeline stages — Read azure-pipelines.yml or .github/workflows/*.yml for current stage names and environment names

Step 3 — Run the staleness audit

For each documentation file, check for each staleness signal:

Signal 1: Resource name mismatch Grep each doc for Azure resource names (patterns like app-, kv-, sql-, afd-, rg-). Compare against the authoritative list from Step 2. Severity: HIGH — wrong resource names in runbooks cause incidents.

Signal 2: Version mismatch Look for version numbers in docs (.NET 6, Node 16, npm 8, Umbraco 12). Compare against package.json, global.json, *.csproj. Severity: MEDIUM — wrong versions in onboarding guides waste developer setup time.

Signal 3: Stale architecture diagrams Look for Mermaid diagrams in docs. Check whether any services named in diagrams appear in recent delete/removal commits or are absent from current IaC files. Severity: HIGH — stale diagrams cause confusion in architecture reviews.

Signal 4: Changed URLs or endpoints Compare URLs in docs against current config. Flag any that don't match a known pattern. Severity: MEDIUM — broken URLs in onboarding guides frustrate new joiners.

Signal 5: ADRs referencing superseded decisions Check ADR status fields. If an ADR is Accepted but a later commit reverts the decision (grep for the technology name in recent git history), flag for review. Severity: MEDIUM — misleading ADRs cause teams to repeat already-made mistakes.

Signal 6: Last-updated header vs. git log If a doc has a "Last updated" date, compare against git log <file> --oneline -1. If the file was changed after the stated date but the header wasn't updated, flag it. Severity: LOW — indicates the doc was patched but the header wasn't maintained.

Signal 7: Orphaned references Grep each doc for file paths referenced as links. Check whether those files exist. Severity: LOW — broken links; easy to fix.

Signal 8: Removed services still documented Grep docs for service/technology names. If a name appears in docs but is absent from all current source files and IaC, flag as potentially orphaned. Severity: MEDIUM — requires human confirmation before removal.

Step 4 — Apply safe auto-updates

Auto-update only when the change is unambiguous (clear before/after from code):

Change type Auto-update Requires human
Version number mismatch (docs say X, code says Y) Yes — update docs to match code If ambiguous (multiple versions)
Last-updated header Yes — update to current date —
Orphaned file links Flag only Yes — may need a replacement link
Resource name changed Yes — if single authoritative name found If multiple candidates
Service removed (no code trace) Flag only Yes — confirm service is retired
ADR status stale Flag only Yes — team must update ADR status
Architecture diagram stale Flag only Yes — diagram regeneration needed

For each auto-update, use Edit to apply the minimal change. Log every change made.

Step 5 — Produce the staleness report

Write DOCS-AUDIT-<YYYY-MM-DD>.md:

# Documentation Audit — <YYYY-MM-DD>

## Summary

| Severity | Issues found | Auto-fixed | Needs human |
|---|---|---|---|
| HIGH | N | N | N |
| MEDIUM | N | N | N |
| LOW | N | N | N |

---

## High-severity findings

### [H1] Stale resource name in RUNBOOK-prod.md
- **File:** `RUNBOOK-prod.md` line 47
- **Found:** `app-acme-prod-uksouth`
- **Authoritative (from infra/main.bicep):** `app-acme-prod-uks`
- **Action:** Auto-fixed ✓

---

## Medium-severity findings

### [M1] Outdated .NET version in ONBOARDING-developer.md
- **File:** `ONBOARDING-developer.md` line 12
- **Found:** `.NET 7`
- **Authoritative (from global.json):** `.NET 8`
- **Action:** Auto-fixed ✓

---

## Low-severity findings

---

## Requires human review

| Finding | File | Reason human needed |
|---|---|---|
| [H2] Sitecore CMP service in diagrams but no CMP config found | ARCHITECTURE.md | Confirm if CMP was decommissioned |
| [M3] ADR-0012 status Accepted but service was removed | docs/adr/ADR-0012.md | Update ADR status to Deprecated |

---

## Files with no issues found

- README.md
- docs/adr/ADR-0001.md
- ...

---

## Auto-updates applied

| File | Change | Before | After |
|---|---|---|---|
| RUNBOOK-prod.md | Resource name | app-acme-prod-uksouth | app-acme-prod-uks |
| ONBOARDING-developer.md | .NET version | .NET 7 | .NET 8 |

Step 6 — Output summary

DOCS AUDIT complete: DOCS-AUDIT-<date>.md
Files audited: <N>
High-severity issues: <N> (<N> auto-fixed, <N> need human)
Medium-severity issues: <N> (<N> auto-fixed, <N> need human)
Low-severity issues: <N>
Auto-updates applied: <N>

Recommended next steps:
1. Review HIGH issues needing human input (listed in report)
2. Run /diagram-suite to regenerate stale architecture diagrams
3. Update ADR statuses flagged in [Requires human review]

References

  • reference.md — staleness signal catalogue, per-doc-type audit checklists, common drift patterns by platform
Technical details
Plugin
documentation-generator
Author
Dakota Smith
Skill name
living-docs-sync
Maturity
experimental
Security review
No security review
Owners
  • engineering
Argument hint
[path to docs folder or specific doc, e.g. 'docs/' or 'RUNBOOK-prod.md']
Allowed tools
  • Read
  • Write
  • Edit
  • Glob
  • Grep
  • Bash(git log --oneline -30 *)
  • Bash(git log --since="30 days ago" --name-only *)
  • Bash(git diff HEAD~10 -- *.bicep *)
  • Bash(git diff HEAD~10 -- *.tf *)
  • Bash(git diff HEAD~10 -- *.json *)
  • Bash(git diff HEAD~10 -- package.json *)
  • Bash(git show --stat HEAD *)
Source
plugins/documentation-generator/skills/living-docs-sync/SKILL.md

Edit this skill on GitHub — opens GitHub's web editor. No git knowledge needed.