soia-dev-doc-sync

soia-dev-doc-sync

Customer-readable explanation

What this skill can do

Reconcile explicit sources of truth such as code, version metadata, and release records item by item with docs/, README, CHANGELOG, VERSION, and other derived documentation, report factual drift, and fix it within the authorized scope.

Customer wants	Skill will do	Customer can see
Check whether documentation is outdated	Establish a source-of-truth inventory and compare each claim with the corresponding evidence	Findings, evidence, severity, and recommended fix order
Synchronize documentation after a release or major change	First update the source of truth, then backfill the derived layer	Scope of changes, verification results, and residual risks

How customers use it

Provide the target repository, the documentation scope to check, and the known sources of truth (for example, manifests, version files, release notes, API schemas, tests, or generated output). If the source-of-truth priority is unclear, confirm it first, and do not use old documentation to corroborate itself.

When overwriting, deletion, publishing, or remote state is involved, first show the target, impact, and patch preview and obtain confirmation. Ordinary single-document creation, pure translation, or copy that does not require factual reconciliation does not trigger this skill.

Dependencies and installation

Installation:

npx skills add soia-team/soia-open-skills -g -a '*' -s soia-dev-doc-sync -y

Hard dependency: read-only access to the target repository and its source-of-truth files. Optionally use the project's existing lint, tests, generators, or link checkers; when absent, truthfully report the verification surfaces not covered.

This skill requires no private configuration. User-specific paths are provided only in the parameters or environment for this run and are not written into the skill.

Logging and completion receipt

完成：<审计或同步的结果>。

真源与范围：<已核实的真源及派生文档范围>
发现：<类别、数量、证据摘要>
文件变化：<更新的文档类别；无改动则写“无”>
验证：<运行的检查及结果>
残余风险：<未验证真源、无法访问的输入或“无”>

Trigger conditions

Documentation needs to be backfilled after a release, version upgrade, architecture or API change;
README, CHANGELOG, VERSION, architecture descriptions, or multilingual pages may be at different factual time slices;
The user requests "doc sync", "documentation reconciliation", or "check whether docs have drifted".

Source-of-truth priority

Before starting, write out the source-of-truth table for this task. The recommended default order is:

Executable or machine-readable facts: code, schemas, manifests, locked versions, generated output, test results;
Explicitly maintained release facts: version files, issued release notes, change records;
Reviewed design or decision records;
Derived narratives such as README, guides, architecture descriptions, and exported pages.

A project may define a higher-priority authoritative source; follow it. If two sources of truth at the same level conflict, stop automatic backfilling and report the conflicting files, fields, and minimal review path. Never modify the source of truth merely to make the documentation consistent.

Drift categories

status-drift: inconsistent lifecycle or support status;
coverage-gap: the source of truth already has a feature, version, or change, but the derived documentation omits it;
version-drift: inconsistent version numbers, release dates, or compatibility ranges;
release-drift: release notes, CHANGELOG, and version timeline contradict one another;
structural-drift: modules, commands, interfaces, configuration items, or counts still reflect old facts;
bilingual-drift: pages in different languages are at different factual slices;
historical-snapshot-gap: historical snapshots do not indicate their point in time and the current source of truth;
link-or-reference-drift: The referenced target has been renamed, deleted, or is no longer an authoritative source.

Each finding must record: the true-source location and excerpt, the derived location and excerpt, the expectation, the observed value, and the recommended action. Write "inferences" separately from "verified facts."

Standard procedure

Define the scope: list the documents, language versions, version windows, and immutable boundaries to be reconciled in this pass.
Read the minimal set of true sources; first run the project's existing generation, lint, or test commands (when read-only/no side effects).
Build a fact table: map each fact to one authoritative source and all derived consumers.
Run automated checks (if any), but manually verify each high-impact finding; a tool returning 0 is not evidence of "no drift."
Fix in dependency order: resolve true-source conflicts first; then version/release facts; then summary pages, READMEs, export pages, and translation pages. Derived layers must not get ahead of upstream facts.
Re-run the relevant checks, and verify key numbers, links, versions, and example commands through a separate path.
Output a receipt; unverified languages, generated artifacts, or external pages must be explicitly listed as residual risk.

Post-write verification contract

Every change must be traceable to this pass's true source or an explicit user decision;
Independently verify version numbers, dates, quantities, commands, and links once;
After fixing one instance of drift, search for other instances of the same term, version, or old identifier in adjacent documents;
Report a pass only when checks were actually run; if not run, state the reason and the executable command;
Keep content layered: factual updates, explanatory text, and historical snapshots must not be mixed into a single sourceless narrative.

Safety boundaries

Do not treat derived documents as true sources in reverse;
Do not fabricate release status, test conclusions, support commitments, or unverified product behavior;
Do not publish, send, overwrite remote documents, or modify version tags without authorization;
Do not write local paths, accounts, keys, private workspaces, or internal organizational processes into reusable documents.

Verification

Static: run the target repository's existing documentation, link, formatting, or generation checks;
Content: spot-check the true-source-to-derived mapping for each type of finding, and re-search for old values;
Regression: confirm the changes did not introduce new version, link, or terminology drift in same-language or cross-language pages.