soia-dev-doc-sync

soia-dev-doc-sync

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 documents, report factual drift, and fix it within the authorized scope.

Customer wants	Skill will do	Customer can see
Check whether documentation is outdated	Build a source-of-truth inventory and compare each claim with its corresponding evidence	Finding, evidence, severity, and recommended fix order
Sync documentation after a release or major change	Update the source of truth first, then backfill the derived layer	Change scope, verification results, and residual risk

How customers use it

Provide the target repository, the documentation scope to inspect, and the known sources of truth (for example manifest, version file, release note, API schema, tests, or generated output). If source-of-truth priority is unclear, confirm it first; do not use old documents to corroborate one another.

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

Dependencies and installation

Installation:

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-dev@soia

When only this one skill is needed, the npx route can be used. Note that the skill will land in the shared source of truth ~/.agents/skills; if the plugin is also installed, the same skill will appear in two indexes and each will drift separately, so choosing one of the two is recommended:

npx skills add soia-team/soia-open-dev-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, generator, or link checker; if missing, 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.

WorkBuddy 's loading unit is role-based experts rather than plugins,npx skills add -a '*' cannot cover it and it must be installed separately, see docs/install/workbuddy.md。

Private information and intermediate data

Sources of truth, derived documents, and diffs may contain non-public product information; read only the reconciliation scope for this run, and do not copy full text into public examples, temporary reports, or receipts.
Documentation patches and user-requested deliverables are written back to the target repository or a user-specified path; this skill does not establish an independent persistent state, cache, or shadow document library.
Intermediate files from tools such as generators and link checkers follow the target repository's conventions; otherwise place them in the operating system temporary directory and clean them up after confirming they are not project artifacts.
Provider credentials remain in the official login state or system credential store. Ordinary config.yml can only store non-secret paths or preferences, and cannot store API keys, cookies, sessions, or document body text.
Receipts store only the minimal evidence for findings, changed paths, and verification summaries; desensitize first when sensitive content needs to be referenced.

Logs and completion receipts

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

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

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 a 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, changelogs;
Reviewed design or decision records;
Derived narratives such as README, guides, architecture descriptions, export pages.

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

Drift classification

status-drift: lifecycle or support status inconsistent;
coverage-gap: the source of truth already has a feature, version, or change, but the derived documentation fails to record it;
version-drift: version number, release date, or compatibility scope inconsistent;
release-drift: release note, CHANGELOG, and version timeline contradict each other;
structural-drift: modules, commands, interfaces, configuration items, or counts are still old facts;
bilingual-drift: different language pages are at different fact slices;
historical-snapshot-gap: historical snapshots do not indicate their time point and 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: source of truth location and excerpt, derived location and excerpt, expected value, observed value, suggested action. Write "inference" separately from "verified fact."

Standard procedure

Limit scope: list the documents, language versions, version window, and immovable boundaries to be reconciled this time.
Read the minimal set of sources of truth; first run the project's existing generation, lint, or test commands (when read-only/no side effects).
Build a fact table: each fact maps 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 source of truth conflicts first; then version/release facts; then summary pages, README, export pages, and translation pages. The derived layer must not lead upstream facts.
Rerun 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 task's source of truth or an explicit user decision;
Independently verify version numbers, dates, counts, 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 pass only when the check was actually run; if not run, state the reason and the executable command;
Keep content layered: fact updates, explanatory text, and historical snapshots must not be mixed into one unsourced narrative.

Security boundaries

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

Verification

Static: Run existing document, link, format, or generation checks in the target repository;
Content: Sample and verify the source-to-derived mapping for each type of finding, and re-search for old values;
Regression: Confirm that the change does not cause new version, link, or terminology drift in same-language or cross-language pages.