Updating a wskill when its source changes

§ 1Purpose

Keep a wskill faithful to its upstream — check each source for drift, and update and re-pin the units only when the source has actually moved.

§ 2Prerequisites

• The wskill declares its sources and a pinned topic.version

§ 3Flowchart

§ 4Steps

Begin when you are notified the upstream moved, or on a regular cadence. The goal is to detect drift between the live source and what the wskill already records — not to re-read everything from scratch.

source upstream {
  kind             = "docs"
  locator          = "https://example.com/manual"
  covers           = "the reference this wskill summarises"
  last_checked     = "2026-06-24"
  reflects_version = "4.2"
}

For each source block, compare the live upstream against the reflects_version it carried when last checked, and refresh last_checked to today. The sources are update-workflow metadata, not topic content — they exist precisely so a review can tell at a glance what each unit was last reconciled against.

If the upstream still matches every source's reflects_version, the wskill is already faithful — take the no branch and stop. If anything moved, take the yes branch to bring the affected units back in line.

Fold each change into the model: edit the concept, entity, fact or procedure units the change touches, keeping each atomic and re-checking its related links. Only touch the units the source actually moved. Where a change raises something only the topic owner can settle (a policy choice, an ambiguity the source doesn't resolve), don't guess — capture it as a question block; the owner answers later via wcl answer wskill.wcl (or the serve --answer questionnaire), and the next sweep folds each :answered question into real units and deletes the block. Sweep the research blocks too: a finding whose subject moved past its applies_to gets re-verified (update checked) or flipped to status = :stale; a finding replaced by new research becomes :superseded with superseded_by naming the replacement.

$ wcl check wskill.wcl
OK
$ just render        # rebuild the book + skill projections

Run wcl check wskill.wcl and rebuild both projections so the change renders cleanly. Then re-pin the metadata: set each touched source's reflects_version to the upstream you reconciled against, and bump topic.version so consumers can tell the wskill has moved.

The wskill faithfully reflects its sources again, and the version pin records which upstream it now describes.