Customer-readable description
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 its corresponding evidence | Findings, evidence, severity, and recommended fix order |
| Synchronize documentation after a release or major change | Update the source of truth first, 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 be checked, and known sources of truth (for example manifest, version files, release notes, API schema, tests, or generated output). If source-of-truth priority is unclear, confirm it first; do not use old documents to corroborate each other.
When coverage, deletion, release, 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-dev-coding-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 this run's parameters or environment and are not written into the skill.
Logs and completion receipt
完成:<审计或同步的结果>。
真源与范围:<已核实的真源及派生文档范围>
发现:<类别、数量、证据摘要>
文件变化:<更新的文档类别;无改动则写“无”>
验证:<运行的检查及结果>
残余风险:<未验证真源、无法访问的输入或“无”>
Trigger conditions
- Documentation needs to be backfilled after a release, version upgrade, or 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, schema, manifest, 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 just to make documentation consistent.
Drift categories
status-drift: lifecycle or support status is inconsistent;coverage-gap: the source of truth already has a feature, version, or change, but the derived documentation omits it;version-drift: version number, release date, or compatibility range is inconsistent;release-drift: release notes, CHANGELOG, and version timeline contradict each other;structural-drift: modules, commands, interfaces, configuration items, or counts still reflect old facts;bilingual-drift: different language pages 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 process
- Define 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 high-impact findings item by item; 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, README, export pages, and translation pages. The derived layer must not get ahead of upstream facts.
- Re-run the relevant checks, and verify key numbers, links, versions, and example commands through another path.
- Output a receipt; unverified languages, generated artifacts, or external pages must be explicitly listed as residual risks.
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 one unsourced narrative.
Security 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, account names, 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: sample and verify 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.