Doc-Sync — Keep Documentation in Sync with the Codebase

skills/j-doc-sync/ is the canonical, hand-edited directory for this skill, per CLAUDE.md's "The Canonical Naming Contract" (the E50 reopening of 2026-09-09, which promoted skills/j-doc-sync/ from generated twin to sole canonical form). The j- prefix is there for collision safety — a real directory under a distinct name, so a host tool shipping its own same-named built-in command cannot shadow it (Claude Code's native skill resolution is a literal-string, directory-name-based match; see project/documentation/skill-authoring.md's "Invocation Convention").

⚠️ scripts/generate-j-alias.sh was retired by E50_S14 and no longer exists — there is nothing to run. This file was previously generated from a bare skills/doc-sync/SKILL.md source; E50_S15 deleted that directory. This file is now the sole canonical, hand-edited source for this skill — edit it directly.

What this skill does

Analyses project source files, compares them against existing documentation, and updates any documentation that is stale, incomplete, or missing. Can be scoped with arguments to focus on specific files or exclude noise.

Argument Parsing

Before doing anything, check the user's message for arguments. Arguments may appear in any order and may be combined in a single invocation.

Examples:

• doc-sync update: docs/API.md source: src/api/
• doc-sync exclude: node_modules, dist update: README.md
• doc-sync source: src/auth/ update: docs/auth.md, docs/security.md
• doc-sync minify: 50 update: docs/API.md
• doc-sync minify: update: README.md (uses default 70%)

All paths are interpreted relative to the project root. The docs/... paths above are examples of a consumer's own documentation files named by the user; doc-sync does not treat docs/ as a default location. When it must pick a home for a new maintainer-internal file, it uses the documentation path from project/configs/workflow.json (paths.documentation, default project/documentation) and reserves docs/ for published-site content (see CLAUDE.md's "Documentation Placement").

Instructions

1. Parse arguments

Extract any update:, source:, exclude:, and minify: values from the user's message.

• Store each as a list: update_targets, source_paths, exclude_paths.
• Store minify as a number minify_pct. If the minify: key is present but has no value, default to 70. If minify: is absent entirely, set minify_pct to null (no minification).
• Merge exclude_paths with the default excludes from assets/default_excludes.txt.

2. Resolve update targets

If update_targets is not empty, use those paths as the documentation files to update.

If update_targets is empty, resolve targets from assets/doc_targets.md:

• Read the file and parse the Documentation Targets list.
• Each entry is a relative path to a documentation file to keep up to date.
• If no entry matches an existing file, skip it and note it as missing.

If neither source has targets (no arguments and no doc_targets), scan the project for documentation files:

• Look for *.md, docs/ (the project's own documentation directory, if it has one — not a default target, and not Jenga's published site, whose source is site/), the documentation path from project/configs/workflow.json (default project/documentation/), documentation/, README*, CHANGELOG*, CONTRIBUTING*.
• Ask the user: "I found the following documentation files. Which should I update?" — present the list and let them select.

3. Resolve analysis sources

If source_paths is not empty, read those files and directories (recursively if directories).

If source_paths is empty, infer sources from each update target:

• Read the existing content of the documentation file.
• Look for mentions of paths, module names, function names, or API routes that hint at what code it describes.
• Use those hints to locate relevant source files in the project.
• Fall back to a broad scan of common source directories (src/, lib/, app/, project root) if no hints are found.

Apply exclude_paths at this step — skip any file or directory matching an excluded path.

4. Analyse for drift

For each update target and its resolved sources:

1. Read the documentation file — understand what it currently claims (structure, API, config, behaviour, examples).
2. Read the source files — extract the current reality (exported functions, routes, config keys, CLI flags, env vars, class names, etc.).
3. Compare — identify:
   • Sections that reference removed or renamed things.
   • Missing documentation for new things added in source.
   • Outdated examples, wrong flag names, stale code snippets.
   • Incorrect or missing configuration keys/values.

4a. Cross-reference .publicignore for "missing documentation" candidates

Every candidate identified above as "missing documentation for new things added in source" ships publicly by default unless this project has adopted /mirror-public. Before flagging any such candidate, check whether it's actually private-only:

1. Check for .publicignore at the repo root. Most projects using this framework will not have one (they haven't adopted /mirror-public) — if it's absent, skip this entire sub-step. Fall through to flagging every "missing documentation" candidate exactly as 3. above already would, with no further filtering.
2. If .publicignore exists, for each "missing documentation" candidate, determine its source path (relative to the repo root) and classify it by running:

   bash "$([ -f scripts/check-publicignore-match.sh ] && echo scripts/check-publicignore-match.sh || echo node_modules/@jenga-ai/agent/scripts/check-publicignore-match.sh)" <path> [<path> ...]

   This reuses /mirror-public's own mirror.sh matching logic (rsync --exclude-from=.publicignore) — a file this script reports BLOCKED is guaranteed to be a file /mirror-public --dry-run would also report as "would be blocked", and vice versa for PUBLIC. It needs no network access and does not require /mirror-public to be configured.
3. BLOCKED → do not flag this candidate as missing documentation. It's private-only and will never ship to the public mirror, so public docs coverage is not applicable.
4. PUBLIC → flag it as usual in step 5's report, and name README.md and project/.wiki/documentation.md (the confirmed canonical full-reference doc — see assets/doc_targets.md) as the target docs to check for coverage of this item.

This sub-step only changes what gets flagged as "missing documentation" in step 3's third bullet — it does not affect the other three drift categories (renamed/removed references, outdated examples, incorrect config keys), which are flagged regardless of .publicignore since they concern existing documentation content, not public-shipping coverage of new source additions.

5. Report findings before updating

Before making any writes, present a concise drift summary per file:

📄 docs/API.md
  ✏️  /api/users route renamed to /api/members in source
  ➕  New endpoint POST /api/invites not documented
  🗑️  Reference to deprecated `--verbose` flag still present

📄 README.md
  ✏️  Setup instructions reference Node 16; project now requires Node 20
  ➕  New environment variable DATABASE_URL not listed

Ask: "Should I apply all updates, or skip any of these?"

6. Apply updates

For each approved update:

• Edit the documentation file in-place — preserve existing structure, tone, and formatting.
• Replace stale references with accurate ones.
• Add new sections or entries for undocumented items.
• Remove or mark deprecated items with a note if full removal seems too aggressive (ask when uncertain).
• Do not alter sections that appear unrelated to the analysed source files.

6a. Minify (if minify_pct is set)

After sync edits are applied (or if only minification was requested), reduce each target file to approximately minify_pct% of its current size:

What to remove — in priority order:

1. Duplicate explanations of the same concept said in multiple ways.
2. Verbose prose that restates what a code example already shows clearly.
3. Historical context, changelogs, or migration notes buried in reference docs.
4. Filler phrases ("It is important to note that…", "As mentioned above…").
5. Redundant examples where one concise example covers the same case as two or three longer ones — keep the most illustrative, remove the rest.
6. Section headers with no meaningful content beneath them.

What to keep — never remove:

• All unique technical facts (function signatures, config keys, env vars, routes, types).
• Code examples that demonstrate something not expressed in prose.
• Warnings, caveats, and known limitations.
• Installation and setup steps.

Process:

1. Calculate the current character count of the file.
2. Target size = current_size × (minify_pct / 100).
3. Remove content following the priority list above until the file is at or below the target size.
4. If the target cannot be reached without removing essential content, stop at the smallest safe size and note the actual reduction achieved.
5. Do not rewrite or paraphrase kept content — only remove.

7. Summarise changes

After all writes are done, print a summary:

✅ Updated 3 documentation files:
   - docs/API.md       (2 sections updated, 1 added)
   - README.md         (setup instructions refreshed)
   - docs/config.md    (3 new env vars added)

🗜️  Minified 2 documentation files:
   - docs/API.md       (4 200 → 2 940 chars, −30%)
   - README.md         (3 100 → 2 170 chars, −30%)

⚠️  Skipped 1 file (no matching sources found):
   - docs/legacy.md

If nothing needed updating, print: ✅ Documentation is already in sync with the source. If minification could not reach the target, note: ⚠️ docs/API.md reduced to X% (target was Y% — essential content limit reached).

8. GitHub Pages site follow-up (E41_S13)

If this run updated project/.wiki/documentation.md, project/.wiki/intro-guide.md, or any project/.wiki/concepts/*.md file, also re-run bash "$([ -f scripts/build-pages-site.sh ] && echo scripts/build-pages-site.sh || echo node_modules/@jenga-ai/agent/scripts/build-pages-site.sh)" afterward. That script deterministically regenerates the GitHub Pages documentation site's wiki-derived pages (site/guides/getting-started.md, site/guides/concepts.md, site/reference/skills.md, site/reference/agents.md, site/reference/hooks.md, site/reference/mcp-tools.md, site/reference/reference.md) from the wiki content this step just updated — without re-running it, the Pages site silently drifts from the wiki the same way README.md and the wiki itself have drifted from each other before. Mention this in the summary output (e.g. 🔄 Re-ran build-pages-site.sh to refresh the Pages site).

Reference files

• assets/doc_targets.md — Editable list of documentation files this skill checks by default.
• assets/default_excludes.txt — Paths always excluded from source analysis unless overridden.
• scripts/check-publicignore-match.sh (repo root) — Used in step 4a to classify "missing documentation" candidates as PUBLIC/BLOCKED per .publicignore, reusing /mirror-public's exact matching semantics.